How to Configure Auto-Update and Manage Configuration Files for OfficeCLI

OfficeCLI stores its runtime configuration in ~/.officecli/config.json, where the AutoUpdate field controls whether the tool checks for and installs updates automatically in the background.

OfficeCLI, the command-line interface maintained by the iOfficeAI/OfficeCLI repository, persists user preferences in a JSON configuration file within your home directory. Learning how to configure auto-update settings and manage this configuration file gives you precise control over the update lifecycle, from disabling background checks to manually auditing version metadata.

Where OfficeCLI Stores Its Configuration

OfficeCLI creates a hidden directory at ~/.officecli/ on first run. Inside this directory, the config.json file maintains the persistent state between sessions.

The JSON structure contains the following fields:

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

• AutoUpdate: Boolean flag that enables or disables the background update checker.
• Log: Toggle for diagnostic logging.
• Version tracking fields: InstalledBinaryVersion, LastUpdateCheck, and LatestVersion are managed automatically by the binary and should not be edited manually.

Managing Auto-Update via the Command Line

The config subcommand provides a programmatic interface to read and write configuration values without touching the raw JSON. In src/officecli/Program.cs, the argument parser detects config as the first argument and delegates execution to UpdateChecker.HandleConfigCommand.

Checking the Current Auto-Update Status

To retrieve the current value of the AutoUpdate field:

officecli config autoupdate

The output prints either true or false based on the value stored in ~/.officecli/config.json.

Disabling Automatic Updates

To prevent OfficeCLI from checking for updates in the background:

officecli config autoupdate false

The command outputs autoupdate = false to confirm the change. Internally, HandleConfigCommand calls SaveConfig() to persist the updated AppConfig.AutoUpdate property.

Enabling Automatic Updates

To restore automatic background checks:

officecli config autoupdate true

The output confirms autoupdate = true. The next time the binary runs, UpdateChecker.CheckInBackground() will consult this flag and proceed with the update check if the value is truthy.

How Configuration Changes Are Processed

The configuration system follows a strict read-modify-write pattern implemented in src/officecli/Core/UpdateChecker.cs.

When you execute a config command:

1. Argument Parsing: Program.cs (lines 4-7) identifies the config subcommand and routes to HandleConfigCommand.
2. Loading: The handler calls LoadConfig() to deserialize ~/.officecli/config.json into an AppConfig instance.
3. Validation: The handler uses ParseHelpers.IsTruthy (defined in src/officecli/Core/ParseHelpers.cs) to interpret string values like true, 1, yes, or on as boolean true, while false, 0, no, and off evaluate to false.
4. Persistence: The updated object is written back to disk via SaveConfig(), overwriting the previous JSON.

The CheckInBackground() method references config.AutoUpdate before spawning any background threads. If the value is false, the method exits immediately, allowing you to control updates manually or via scheduled maintenance windows.

Manual Configuration File Management

For bulk edits or inspection, you can interact with the raw JSON directly.

Viewing the Raw Configuration

To inspect the entire configuration object, including internal version tracking:

cat ~/.officecli/config.json

Editing the Configuration Directly

To modify multiple settings at once or change paths not exposed via the CLI:

$EDITOR ~/.officecli/config.json

When editing manually, ensure the JSON remains valid; syntax errors will cause LoadConfig() to fail on the next run. Common manual tweaks include:

• Setting "AutoUpdate": false to globally disable updates across environments.
• Adjusting "Log": true to enable verbose debugging without using the CLI.

Clearing Log Files

While managing configuration, you may also need to clear accumulated diagnostic logs. The config command supports this via:

officecli config log clear

This operation is handled within the same configuration management logic in UpdateChecker.cs but targets separate log files rather than the JSON configuration store.

Summary

• Configuration location: OfficeCLI stores settings in ~/.officecli/config.json.
• Auto-update control: The AutoUpdate field determines whether UpdateChecker.CheckInBackground() runs.
• CLI interface: Use officecli config autoupdate [true|false] to toggle settings programmatically.
• Parsing logic: Values are interpreted via ParseHelpers.IsTruthy, accepting true, 1, yes, etc.
• Manual editing: Advanced users can edit the JSON directly for bulk changes, but must preserve valid syntax.

Frequently Asked Questions

Where is the OfficeCLI configuration file stored?

The configuration file is located at ~/.officecli/config.json within the current user's home directory. This path is read by LoadConfig() and written by SaveConfig() in src/officecli/Core/UpdateChecker.cs.

What values can I use when setting the autoupdate option?

OfficeCLI accepts any truthy or falsy string that ParseHelpers.IsTruthy recognizes. Valid truthy values include true, 1, yes, and on. Valid falsy values include false, 0, no, and off. These are normalized to boolean values before being stored in the JSON file.

Does disabling auto-update prevent me from updating OfficeCLI manually?

No. Disabling AutoUpdate only stops the automatic background check implemented in UpdateChecker.CheckInBackground(). It does not block manual updates or version checks triggered explicitly by other command flags.

Can I add custom fields to the configuration file?

While the JSON file can technically hold additional key-value pairs, only AutoUpdate, Log, InstalledBinaryVersion, LastUpdateCheck, and LastestVersion are referenced by the current source code in iOfficeAI/OfficeCLI. Adding custom fields will not affect runtime behavior unless you modify the source and recompile.

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