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

> Learn to configure OfficeCLI auto-update and manage config files at ~/.officecli/config.json. Keep your tool updated effortlessly.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/config.json) file maintains the persistent state between sessions.

The JSON structure contains the following fields:

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

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

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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs).

When you execute a `config` command:

1. **Argument Parsing**: [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
cat ~/.officecli/config.json

```

### Editing the Configuration Directly

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

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

```bash
officecli config log clear

```

This operation is handled within the same configuration management logic in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.