# How to Configure OfficeCLI Auto-Update Behavior and Config File Location

> Learn how to configure OfficeCLI auto-update behavior and find its config file at ~/.officecli/config.json. Manage updates easily with officecli config autoupdate.

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

---

**OfficeCLI stores its auto-update settings in `~/.officecli/config.json` (falling back to [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json) in read-only containers) and defaults to checking for updates every 24 hours, which you can toggle via the `officecli config autoupdate` command or by editing the JSON directly.**

The **iOfficeAI/OfficeCLI** repository implements a self-updating mechanism that runs silently in the background. According to the source code in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs), the tool manages its configuration through a simple JSON file that controls update frequency, logging, and whether automatic upgrades are permitted.

## Configuration File Location and Storage

OfficeCLI uses a deterministic path resolution strategy that prioritizes the user's home directory while providing a fallback for containerized environments.

### Primary Config Path

The primary configuration file is **`~/.officecli/config.json`**. 

In [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs), the paths are constructed at lines 28-30:

- `ConfigDir` resolves to `$HOME/.officecli`
- `ConfigPath` resolves to `$HOME/.officecli/config.json`

The CLI creates this directory automatically if it does not exist when `CheckInBackground` is invoked.

### Container Fallback Path

When running inside Docker, Kubernetes, AWS Lambda, or Google Cloud Run where the home directory is read-only, OfficeCLI falls back to **[`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json)**.

This logic appears at lines 61-65 in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs), ensuring the tool remains functional in serverless and ephemeral compute environments.

## Understanding the Auto-Update Configuration Schema

The configuration file maps to the `AppConfig` class defined in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 97-105):

```csharp
public class AppConfig
{
    public DateTime? LastUpdateCheck { get; set; }
    public string?   LatestVersion      { get; set; }
    public bool      AutoUpdate  = true;   // <-- defaults to true
    public bool      Log;
    public string?   InstalledBinaryVersion;
    public string?   LastSkillRefreshVersion;
}

```

**Key fields:**
- **`AutoUpdate`**: Boolean flag defaulting to `true` (lines 100-102). When enabled, the CLI attempts to upgrade itself automatically.
- **`LastUpdateCheck`**: Timestamp of the last successful check, used to enforce the 24-hour check interval.
- **`LatestVersion`**: Caches the most recent version available from the repository.

## How the Auto-Update Mechanism Works

The update flow operates on every CLI invocation through a background process to avoid blocking user commands.

### The Check Interval Logic

1. **`CheckInBackground`** (line 73) loads the config and verifies the `AutoUpdate` flag.
2. If `AutoUpdate` is `true` and `LastUpdateCheck` exceeds the `CheckIntervalHours` threshold (24 hours), the method spawns a detached process at lines 77-80.
3. This process executes the hidden command `__update-check__`, which triggers **`RunRefresh`** (lines 93-164).

### The Update Process

**`RunRefresh`** performs the following operations:
- Resolves the latest release from the official mirror or GitHub.
- Verifies the SHA-256 hash of the download.
- Downloads the appropriate binary asset for your platform.
- Executes a smoke test via `RunVersionVerify`.
- Replaces the existing executable (or writes a `.update` file on Windows for replacement on next start).

### Package Manager Restrictions

If the binary is installed via **Homebrew**, the updater aborts after recording the latest version without modifying the executable (lines 58-60). This prevents conflicts with Homebrew's own version management.

## Configuring Auto-Update Settings via CLI

OfficeCLI exposes a `config` sub-command implemented in `HandleConfigCommand` (lines 30-86) that allows runtime modification without manual file editing.

### Reading the Current Setting

```bash
officecli config autoupdate

```

Output: `true` or `false`.

### Enabling Auto-Update

```bash
officecli config autoupdate true

```

The command updates the in-memory `AppConfig` and persists it via `SaveConfig` (lines 82-88).

### Disabling Auto-Update

```bash
officecli config autoupdate false

```

### Example: Disabling on Shared Workstations

```bash

# Verify current state

$ officecli config autoupdate
true

# Disable permanently

$ officecli config autoupdate false
autoupdate = false

# Confirm change

$ officecli config autoupdate
false

```

After execution, `~/.officecli/config.json` contains:

```json
{
  "autoUpdate": false,
  "log": false,
  "lastUpdateCheck": null,
  "latestVersion": null,
  "installedBinaryVersion": null,
  "lastSkillRefreshVersion": null
}

```

The CLI ignores unknown JSON keys, allowing you to add custom metadata without breaking functionality.

## Programmatic Configuration Management

You can interact with the configuration directly using the `UpdateChecker` class.

### Reading Config Programmatically

```csharp
using OfficeCli.Core;

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

// Inspect the auto-update flag
bool isAuto = cfg.AutoUpdate;
Console.WriteLine($"Auto-update enabled: {isAuto}");

```

### Modifying Config from Code

```csharp
AppConfig cfg = UpdateChecker.LoadConfig();
cfg.AutoUpdate = false;               // disable automatic updates
UpdateChecker.SaveConfig(cfg);        // persists to ~/.officecli/config.json

```

### Simulating Background Checks

For testing purposes, you can force an immediate refresh regardless of the 24-hour interval:

```csharp
// Normally invoked by the spawned background process
UpdateChecker.RunRefresh();

```

## Summary

- **Configuration location**: Primary path is `~/.officecli/config.json`; containers use [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json) when the home directory is read-only.
- **Default behavior**: `AutoUpdate` defaults to `true` with a 24-hour check interval defined in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs).
- **CLI control**: Use `officecli config autoupdate <true|false>` to toggle settings without editing files.
- **Update flow**: `CheckInBackground` spawns a silent process running `__update-check__`, which executes `RunRefresh` to download, verify, and replace the binary.
- **Homebrew exception**: Automatic replacement is disabled for Homebrew-managed installations to prevent package manager conflicts.

## Frequently Asked Questions

### Where is the OfficeCLI configuration file stored?

OfficeCLI stores its configuration at `~/.officecli/config.json` by default. The path is constructed in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 28-30) using the `ConfigDir` and `ConfigPath` properties. In containerized environments where the home directory is read-only—such as Docker, Kubernetes, or Lambda—the tool falls back to [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json) (lines 61-65).

### How do I disable automatic updates in OfficeCLI?

Run the command `officecli config autoupdate false` to disable the feature permanently. This updates the `AutoUpdate` field in the JSON configuration file to `false`. Alternatively, manually edit `~/.officecli/config.json` and set `"autoUpdate": false`. The change takes effect immediately on the next CLI invocation.

### What happens if OfficeCLI is installed via Homebrew?

When OfficeCLI detects it is managed by Homebrew, the auto-updater aborts after recording the latest version information but does not attempt to replace the binary. This check occurs at lines 58-60 in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) to prevent conflicts with Homebrew's own versioning system. You should use `brew upgrade officecli` instead to update Homebrew-managed installations.

### Can I manually trigger an update check in OfficeCLI?

While the standard flow relies on the 24-hour interval triggered by `CheckInBackground`, you can programmatically force a refresh by calling `UpdateChecker.RunRefresh()` from within a C# application referencing the OfficeCLI core library. This method bypasses the timestamp check and immediately attempts to resolve, download, and install the latest version from the official repository.