How to Configure OfficeCLI Auto-Update Behavior Using the Config Command and Environment Variables

You can disable OfficeCLI auto-updates permanently by running officecli config autoUpdate false, or skip them for a single invocation by setting the OFFICECLI_SKIP_UPDATE=1 environment variable.

OfficeCLI automatically checks for new releases in the background every time you run a command. This behavior is governed by the UpdateChecker.cs class in the iOfficeAI/OfficeCLI repository. Understanding how to configure this feature helps you avoid unexpected delays in CI pipelines or control network traffic in restricted environments.

The Default Auto-Update Configuration

By default, OfficeCLI stores its configuration in a JSON file located at ~/.officecli/config.json. This file contains an AutoUpdate boolean flag initialized to true.

The configuration path is hardcoded in src/officecli/Core/UpdateChecker.cs at line 30. When the CLI starts, it reads this file to determine whether to contact GitHub for release information.

Persistent Configuration with the officecli config Command

The CLI provides a built-in config command to modify settings without editing JSON manually. This command is parsed in UpdateChecker.cs between lines 444–492.

Disabling Auto-Updates Permanently

officecli config autoUpdate false

This writes "AutoUpdate": false to ~/.officecli/config.json. Subsequent invocations will skip the GitHub release check entirely.

Re-Enabling Auto-Updates

officecli config autoUpdate true

This restores the default behavior. The next CLI invocation will resume checking for updates based on the configured interval.

One-Off Override with Environment Variables

For scenarios requiring temporary suppression—such as CI/CD pipelines or air-gapped environments—OfficeCLI respects the OFFICECLI_SKIP_UPDATE environment variable.

In src/officecli/Program.cs at line 268, the CLI checks this variable before entering the update routine:

OFFICECLI_SKIP_UPDATE=1 officecli get mydoc.docx some/path

This skips the update check for that single execution without modifying the persisted configuration.

PowerShell Equivalent

$env:OFFICECLI_SKIP_UPDATE = '1'
officecli get mydoc.docx some/path

How the Update Decision Logic Works

The core update flow in UpdateChecker.cs (lines 66–88) evaluates multiple conditions:

if (config.AutoUpdate) {
    if (!config.LastUpdateCheck.HasValue ||
        (DateTime.UtcNow - config.LastUpdateCheck.Value).TotalHours >= CheckIntervalHours) {
        // Contact GitHub for latest release
    }
}

Even when AutoUpdate is enabled, the CLI respects a minimum interval between checks to avoid excessive API requests. The LastUpdateCheck timestamp and CheckIntervalHours threshold prevent redundant network calls.

Programmatic Configuration (C#)

For library consumers or custom tooling, you can manipulate configuration directly:

var cfg = OfficeCLI.Core.UpdateChecker.LoadConfig();
cfg.AutoUpdate = false;
OfficeCLI.Core.UpdateChecker.SaveConfig(cfg);

This bypasses the CLI interface and integrates configuration management into your own applications.

Summary

• Persistent control: Use officecli config autoUpdate <true|false> to modify ~/.officecli/config.json
• Temporary override: Set OFFICECLI_SKIP_UPDATE=1 for single-run suppression
• Key implementation files: UpdateChecker.cs (config handling and update logic) and Program.cs (environment variable check)
• Default state: Auto-update is enabled with rate limiting via CheckIntervalHours

Frequently Asked Questions

How do I completely disable OfficeCLI auto-updates?

Run officecli config autoUpdate false. This persists the setting across all future invocations by writing to ~/.officecli/config.json. The change takes effect immediately without requiring a restart.

Can I skip the update check just once without changing config?

Yes. Set the environment variable OFFICECLI_SKIP_UPDATE=1 before running your command. This is ideal for CI pipelines where you want deterministic execution times without permanent configuration changes.

Where is the OfficeCLI configuration file stored?

The default location is ~/.officecli/config.json on all platforms. This path is defined at line 30 in src/officecli/Core/UpdateChecker.cs and contains the AutoUpdate flag plus metadata like LastUpdateCheck.

Does OfficeCLI check for updates on every single command?

No. Even when enabled, the update logic in UpdateChecker.cs enforces a minimum interval between checks using CheckIntervalHours. The CLI only contacts GitHub when sufficient time has elapsed since the last check.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}