How to Configure OfficeCLI Auto-Update Settings and Locate the Config File

OfficeCLI stores auto-update settings in ~/.officecli/config.json (or /tmp/officecli-config.json in containers), where the AutoUpdate property defaults to true; manage this via the officecli config autoupdate command or by editing the JSON directly.

OfficeCLI automatically checks for new releases every 24 hours and can self-update unless installed via Homebrew. For users in enterprise environments or running containerized workloads, controlling this behavior through the configuration file is essential for stability and compliance.

Where OfficeCLI Stores Its Configuration

OfficeCLI persists settings in a JSON file located within a hidden directory in the user's home folder.

Primary Configuration Path

The main configuration file is located at:

~/.officecli/config.json

According to the source code in src/officecli/Core/UpdateChecker.cs, the application builds this path using the UpdateChecker.ConfigDir property (resolving to $HOME/.officecli) and the ConfigPath property (resolving to $HOME/.officecli/config.json) during initialization (lines 28–30).

Fallback for Container Environments

When running inside Docker, Kubernetes, Lambda, or Cloud Run environments where the home directory is read-only, OfficeCLI automatically falls back to:

/tmp/officecli-config.json

This fallback logic is implemented in lines 61–65 of UpdateChecker.cs, ensuring the CLI can still record state even in restricted environments.

Configuration Schema and Defaults

The configuration structure is defined by the AppConfig class within UpdateChecker.cs:

public class AppConfig
{
    public DateTime? LastUpdateCheck { get; set; }
    public string?   LatestVersion   { get; set; }
    public bool      AutoUpdate = true;   // Defaults to enabled
    public bool      Log;
    public string?   InstalledBinaryVersion;
    public string?   LastSkillRefreshVersion;
}

Key point: The AutoUpdate field defaults to true (lines 100–102). The CLI uses this flag to determine whether to spawn background update checks.

How to Change Auto-Update Settings

OfficeCLI exposes a config sub-command implemented in HandleConfigCommand (lines 30–86 of UpdateChecker.cs).

Check Current Status

To view whether auto-updates are currently enabled:

officecli config autoupdate

This outputs either true or false based on the current configuration file.

Enable Auto-Updates

To explicitly enable automatic updates:

officecli config autoupdate true

Disable Auto-Updates

To prevent the CLI from checking for or downloading updates:

officecli config autoupdate false

These commands update the in-memory AppConfig instance and persist changes via the SaveConfig method (lines 82–88).

Manual Configuration Editing

You can also edit the JSON directly. For example, to disable updates on a shared workstation:

# Create the directory if it doesn't exist

mkdir -p ~/.officecli

# Write the configuration

echo '{"autoUpdate": false}' > ~/.officecli/config.json

The CLI ignores unknown JSON keys and preserves existing values, allowing safe manual modifications.

Understanding the Auto-Update Implementation

When you run any OfficeCLI command, the CheckInBackground method executes (invoked from the entry point in Program.cs). This method:

1. Creates the config directory and loads the JSON via LoadConfig (lines 73–75).
2. Checks the AutoUpdate flag and the LastUpdateCheck timestamp against the 24-hour interval (CheckIntervalHours = 24).
3. Spawns a background process executing the hidden command __update-check__ if the interval has passed and auto-updates are enabled (lines 77–80).

The background process runs RunRefresh (lines 93–164), which:

• Resolves the latest version from the official mirror or GitHub.
• Verifies the SHA-256 hash of the download.
• Downloads the appropriate binary asset.
• Performs a smoke test via RunVersionVerify.
• Replaces the existing executable (or leaves a .update file on Windows for replacement during the next run).

Note: If the binary is managed by Homebrew, the updater aborts after recording the latest version without modifying the installation (lines 58–60).

Programmatic Configuration Access

For developers extending OfficeCLI, the UpdateChecker class exposes static methods to interact with configuration:

using OfficeCli.Core;

// Load configuration (searches home directory, then /tmp fallback)
AppConfig cfg = UpdateChecker.LoadConfig();

// Inspect auto-update status
if (cfg.AutoUpdate) {
    Console.WriteLine("Auto-updates are enabled");
}

// Modify configuration
cfg.AutoUpdate = false;
UpdateChecker.SaveConfig(cfg);  // Persists to ~/.officecli/config.json

Summary

• Config File: Located at ~/.officecli/config.json (or /tmp/officecli-config.json in containers).
• Default Behavior: Auto-updates are enabled by default (AutoUpdate: true).
• Control Method: Use officecli config autoupdate true|false or edit the JSON directly.
• Check Frequency: Updates are checked once every 24 hours via a background process.
• Source Location: All logic resides in src/officecli/Core/UpdateChecker.cs.

Frequently Asked Questions

How do I completely disable OfficeCLI auto-updates?

Run officecli config autoupdate false or manually set "autoUpdate": false in ~/.officecli/config.json. This prevents the CLI from spawning background update checks on subsequent invocations.

Why does OfficeCLI use /tmp for configuration in some environments?

When OfficeCLI detects it is running in a container with a read-only home directory (common in Docker, Kubernetes, or Lambda), it falls back to /tmp/officecli-config.json to ensure it can still record state without write permissions in the user's home folder.

Will OfficeCLI update itself if installed via Homebrew?

No. According to lines 58–60 in UpdateChecker.cs, the updater detects Homebrew-managed installations and aborts the self-update process after recording the latest version, deferring to Homebrew's own update mechanism.

What happens if I set an invalid value in config.json?

The CLI deserializes the JSON into the AppConfig class, ignoring unknown properties. If you corrupt the JSON syntax, the application will likely regenerate the file with defaults or fail gracefully, though manual editing should preserve valid JSON structure to ensure settings are respected.

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