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

> Learn how to configure OfficeCLI settings using JSON config and CLI commands. Safely update autoupdate and log preferences without manual file edits. Get the complete guide.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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:

```bash
~/.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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
officecli config

```

To retrieve a specific key:

```bash
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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
OFFICECLI_SKIP_UPDATE=1 officecli view document.docx html

```

Or equivalently:

```bash
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:

```json
{
  "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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.