How to Configure Auto-Update and Runtime Settings for OfficeCLI

Use the officecli config command to read and write settings in ~/.officecli/config.json, where the AutoUpdate property controls whether the tool checks for new releases in the background.

OfficeCLI stores its runtime configuration in a JSON file located in the user's home directory. When you configure auto-update and runtime settings for OfficeCLI using the config sub-command, the tool modifies this file via the UpdateChecker.HandleConfigCommand method, allowing you to control background update checks and logging behavior without manually editing JSON.

Where OfficeCLI Stores Runtime Settings

OfficeCLI persists all runtime configuration in ~/.officecli/config.json. This file contains the AutoUpdate boolean that governs whether the background update mechanism runs, along with metadata fields like InstalledBinaryVersion, LastUpdateCheck, and LatestVersion.

{
  "AutoUpdate": true,
  "Log": false,
  "InstalledBinaryVersion": "1.0.137",
  "LastUpdateCheck": "2026-07-17T12:34:56Z",
  "LatestVersion": "1.0.150"
}

The file is created automatically after the first run. Only the AutoUpdate and Log properties are typically modified by users; version tracking fields are managed internally by the UpdateChecker class.

Configuring Auto-Update Settings via the Command Line

The config sub-command delegates to UpdateChecker.HandleConfigCommand in src/officecli/Core/UpdateChecker.cs (lines 30-48). This method uses LoadConfig() to read the current state and SaveConfig to persist changes after parsing boolean values through ParseHelpers.IsTruthy.

Check the Current Auto-Update Status

To read the current value without modifying it:

officecli config autoupdate

The command retrieves the value from the in-memory AppConfig object that was loaded from disk.

Disable Automatic Updates

To stop OfficeCLI from checking for updates in the background:

officecli config autoupdate false

This sets AutoUpdate to false. Subsequently, when UpdateChecker.CheckInBackground() executes, it consults this property and skips the update check if disabled.

Re-enable Automatic Updates

To restore background update checks:

officecli config autoupdate true

The implementation in src/officecli/Core/UpdateChecker.cs accepts truthy values including true, 1, yes, or on through the ParseHelpers.IsTruthy utility.

Managing Additional Runtime Settings

Beyond auto-updates, the configuration system supports logging controls. While less commonly modified than the auto-update setting, you can clear the log file using:

officecli config log clear

This demonstrates the extensibility of the configuration handler for managing other runtime behaviors.

How Configuration Commands Work in the Source Code

In src/officecli/Program.cs, the application detects the config command through the conditional block if (args.Length >= 2 && args[0] == "config") and routes execution to UpdateChecker.HandleConfigCommand alongside the argument array.

The HandleConfigCommand method implements a read/write pattern:

• Reading Mode: When only a configuration key is provided (e.g., autoupdate or log), the method prints the current stored value.
• Writing Mode: When a second argument is present, it parses the new value using ParseHelpers.IsTruthy (defined in src/officecli/Core/ParseHelpers.cs), updates the corresponding property on the AppConfig instance, and persists the change via SaveConfig.

The auto-update execution logic itself resides in CheckInBackground(), which loads the configuration and checks config.AutoUpdate before spawning a background refresh operation.

Manual Configuration File Editing

For bulk changes or automation scripts, you can edit ~/.officecli/config.json directly without using the CLI:

$EDITOR ~/.officecli/config.json

Example manual configuration:

{
  "AutoUpdate": false,
  "Log": true,
  "InstalledBinaryVersion": "1.0.137",
  "LastUpdateCheck": "2026-07-17T12:34:56Z",
  "LatestVersion": "1.0.150"
}

After saving, OfficeCLI reads these values on next launch. Ensure your JSON remains valid to prevent runtime parsing errors.

Summary

• OfficeCLI stores runtime settings in ~/.officecli/config.json under the current user's home directory.
• Use officecli config autoupdate [true|false] to control whether the application checks for updates in the background.
• The UpdateChecker.HandleConfigCommand method in src/officecli/Core/UpdateChecker.cs handles all CLI configuration changes, utilizing LoadConfig() and SaveConfig.
• Boolean parsing uses ParseHelpers.IsTruthy, supporting values like true, 1, yes, and on.
• Manual editing of the JSON file is safe for advanced configuration or automation workflows.

Frequently Asked Questions

Where does OfficeCLI store its configuration file?

OfficeCLI stores its configuration in ~/.officecli/config.json within the current user's home directory. This JSON file persists the AutoUpdate setting, logging preferences, and version tracking metadata between sessions. The file is created automatically after the first tool execution.

How do I completely disable automatic updates for OfficeCLI?

Run officecli config autoupdate false in your terminal. This sets the AutoUpdate property to false in the configuration file, preventing the UpdateChecker.CheckInBackground() method from executing background version checks when the CLI starts.

What values can I use when setting boolean configuration options?

According to src/officecli/Core/ParseHelpers.cs, the IsTruthy method accepts true, 1, yes, or on as truthy values. Any other input string is treated as false, providing flexibility in how you specify settings via the command line.

Can I change configuration settings without using the CLI command?

Yes. You can manually edit ~/.officecli/config.json with any text editor. This approach is useful for changing multiple settings at once or when automating deployments across multiple machines, though you must ensure valid JSON syntax to prevent parsing errors on startup.

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