How to Configure OfficeCLI Settings: Complete Guide to JSON Config and CLI Commands

OfficeCLI stores user-level configuration in ~/.officecli/config.json and provides a config sub-command to safely read or modify settings like autoupdate and log without editing files manually.

The iOfficeAI/OfficeCLI repository exposes a straightforward configuration system that persists your preferences across sessions. Whether you need to disable background update checks or enable command logging, you can manage these settings through the built-in CLI interface or by editing the underlying JSON directly.

Configuration File Location and Structure

OfficeCLI maintains a dedicated directory under your home folder for all user-specific data.

The config.json File

The primary configuration file resides at:

~/.officecli/config.json

This JSON file stores key-value pairs that control runtime behavior. The CLI uses a strongly-typed AppConfig class (defined in the source generation pipeline) to serialize and deserialize these values. When you run configuration commands, the UpdateChecker.HandleConfigCommand method in src/officecli/Core/UpdateChecker.cs (lines 430-475) handles the read/write operations atomically.

Using the config Command

The config sub-command provides a safe interface for inspecting and modifying settings without risking JSON syntax errors.

Viewing Current Settings

To display all current configuration values, run:

officecli config

To retrieve a specific key:

officecli config autoupdate

Modifying Configuration Values

Change settings by passing the key and value as arguments. The CLI accepts truthy strings like true, 1, or yes for boolean flags:

# Disable automatic background updates

officecli config autoupdate false

# Enable file logging for command activity

officecli config log true

Validation and Error Handling

The HandleConfigCommand method validates inputs before writing to disk. If you provide an unknown key or invalid value, the CLI reports the error on stderr with a usage hint and exits without modifying ~/.officecli/config.json.

Supported Configuration Keys

As implemented in the current main branch, the following keys are officially supported:

• autoupdate (boolean): Controls whether OfficeCLI automatically checks for newer binary releases in the background. Set to false to disable this behavior.
• log (boolean): Enables a simple file logger that writes command activity to ~/.officecli/officecli.log.

Environment Variables and Flags

For temporary overrides that don't persist to the config file, use environment variables or command-line flags.

In src/officecli/Program.cs (lines 19-21), the CLI checks for the OFFICECLI_SKIP_UPDATE environment variable. Setting this to 1 or using the --skip-update flag suppresses the background update check for a single execution:

OFFICECLI_SKIP_UPDATE=1 officecli view document.docx html

Or equivalently:

officecli view document.docx html --skip-update

Manual Configuration (Advanced)

You can edit ~/.officecli/config.json directly with any text editor. The CLI preserves unknown keys for future extensions, though it only validates and acts upon recognized settings like AutoUpdate and Log.

Example file structure:

{
  "AutoUpdate": false,
  "Log": true,
  "InstalledBinaryVersion": "1.2.3",
  "LastUpdateCheck": "2024-07-10T14:32:00Z"
}

Changes made manually take effect immediately for the next command invocation.

Summary

• OfficeCLI stores persistent settings in ~/.officecli/config.json as JSON.
• The config sub-command in src/officecli/Program.cs dispatches to UpdateChecker.HandleConfigCommand for safe, validated updates.
• Supported keys include autoupdate and log, accepting boolean values.
• Use the OFFICECLI_SKIP_UPDATE environment variable or --skip-update flag for temporary suppression of update checks.
• Manual editing of the JSON file is supported for advanced users, with the CLI preserving unrecognized keys.

Frequently Asked Questions

Where does OfficeCLI store its configuration file?

OfficeCLI stores user-level configuration at ~/.officecli/config.json in your home directory. This path is hardcoded in the AppConfig handling logic within src/officecli/Core/UpdateChecker.cs.

How do I disable automatic update checks in OfficeCLI?

Run officecli config autoupdate false to persistently disable background update checks. Alternatively, set the environment variable OFFICECLI_SKIP_UPDATE=1 before a single command to suppress checks temporarily without changing the configuration file.

What happens if I enter an invalid configuration key?

The HandleConfigCommand method validates your input against known keys. If you specify an unrecognized key, OfficeCLI prints an error message to stderr and aborts the operation, leaving ~/.officecli/config.json unchanged.

Can I use environment variables instead of the config file?

Yes. While persistent settings belong in config.json, you can use the OFFICECLI_SKIP_UPDATE environment variable to override specific behaviors for individual sessions. However, most settings like autoupdate and log must be configured via the config command or direct JSON editing.

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