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

> Learn how to configure OfficeCLI auto-update settings and find the config file at ~/.officecli/config.json. Easily manage updates via command or direct JSON editing for streamlined workflows.

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

---

**OfficeCLI stores auto-update settings in `~/.officecli/config.json` (or [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//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:

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

```

According to the source code in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
/tmp/officecli-config.json

```

This fallback logic is implemented in lines 61–65 of [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs):

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

### Check Current Status

To view whether auto-updates are currently enabled:

```bash
officecli config autoupdate

```

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

### Enable Auto-Updates

To explicitly enable automatic updates:

```bash
officecli config autoupdate true

```

### Disable Auto-Updates

To prevent the CLI from checking for or downloading updates:

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

```bash

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

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