# How to Configure Auto-Update Behavior in OfficeCLI Using Config Files and CLI Commands

> Configure OfficeCLI auto-update behavior using config files or CLI commands. Learn how to enable or disable automatic updates for OfficeCLI easily.

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

---

**You control OfficeCLI's auto-update behavior through the `autoUpdate` boolean in `~/.officecli/config.json` or via the `officecli config autoUpdate <true|false>` command; no dedicated environment variable exists for user configuration.**

OfficeCLI, the open-source CLI tool from the iOfficeAI repository, manages its self-updating mechanism through a per-user JSON configuration system. The `UpdateChecker` class in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs) provides both the background update logic and a built-in config command interface. Understanding how to manipulate the `AppConfig` settings allows you to enable or disable automatic updates across your development environments.

## Where OfficeCLI Stores Auto-Update Settings

OfficeCLI persists user preferences in a dedicated configuration directory. According to the source code in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs), the `UpdateChecker.ConfigDir` property points to `~/.officecli`, while `ConfigPath` resolves to `~/.officecli/config.json`【5†L28-L31】.

The `AppConfig` class defines the schema for this JSON file, including the **critical `AutoUpdate` boolean field** that defaults to `true`【5†L13-L18】. This single flag determines whether the application checks for and applies new versions in the background.

When running inside restricted environments such as containers where the home directory may be read-only, OfficeCLI falls back to [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json)【5†L73-L78】.

## How to Check and Modify Auto-Update Settings

You can interact with the configuration using the built-in `officecli config` command implemented in `HandleConfigCommand`, or by manually editing the JSON file.

### Using the CLI Command

The `HandleConfigCommand` method (lines 44-86 in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs)) supports reading and writing config values:

**Check the current setting:**

```bash
officecli config autoUpdate

```

**Disable auto-updates:**

```bash
officecli config autoUpdate false

```

**Enable auto-updates:**

```bash
officecli config autoUpdate true

```

When you provide a second argument, the command writes the new value to the config file and persists it to disk immediately.

### Editing the Config File Directly

You can manually create or modify `~/.officecli/config.json`:

```json
{
  "autoUpdate": false,
  "log": false,
  "lastUpdateCheck": "2026-07-31T12:00:00Z"
}

```

Save this file and OfficeCLI will respect the `autoUpdate` value on the next invocation.

## How the Auto-Update Logic Works

The update mechanism follows a strict gate-checking pattern controlled by your config:

1. **Startup**: [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs) invokes `UpdateChecker.CheckInBackground()` on every run.
2. **Config Loading**: The method calls `LoadConfig()` to read from `~/.officecli/config.json` (or the `/tmp` fallback).
3. **Gate Check**: If `config.AutoUpdate` is `false`, the method returns early and skips the background refresh entirely【5†L66-L68】.
4. **Background Spawn**: Only when `config.AutoUpdate` is `true` and a day has passed since the last check does the system spawn a background process to query GitHub for new releases【5†L84-L88】.
5. **Application**: The background process (`RunRefresh()`) downloads and verifies the binary, writing a `.update` file. The next process start applies this pending update—again gated by the `AutoUpdate` setting.

## Environment Variables vs. Config Files

**There is no dedicated environment variable** for controlling auto-update behavior in user-facing scenarios. The codebase only references `OFFICECLI_SKIP_UPDATE` as an internal mechanism to prevent child processes from recursively triggering updates during the refresh cycle. All user-level toggling must occur through the config file or the `officecli config` command interface.

## Summary

- OfficeCLI stores auto-update preferences in `~/.officecli/config.json` via the `AppConfig` class.
- The ** `autoUpdate` ** boolean (default `true`) controls whether `CheckInBackground()` executes the update logic.
- Use `officecli config autoUpdate <true|false>` to toggle the setting without manually editing JSON.
- Container environments automatically fall back to [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json) when the home directory is inaccessible.
- Environment variables like `OFFICECLI_SKIP_UPDATE` are reserved for internal process management and should not be used for user configuration.

## Frequently Asked Questions

### Where is the OfficeCLI config file located?

OfficeCLI stores its configuration at `~/.officecli/config.json` on standard systems. If the application detects a container environment or an unwritable home directory, it automatically falls back to [`/tmp/officecli-config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main//tmp/officecli-config.json) to ensure the config remains mutable.

### How do I disable auto-updates in OfficeCLI?

Run the command `officecli config autoUpdate false` to disable automatic updates. Alternatively, manually set `"autoUpdate": false` in the JSON config file. When this value is `false`, the `CheckInBackground()` method skips both the update check and any pending update application.

### Is there an environment variable to disable auto-updates?

No, OfficeCLI does not expose a user-facing environment variable for controlling auto-update behavior. The only related variable, `OFFICECLI_SKIP_UPDATE`, is used internally to prevent recursive update checks in child processes. Users must use the config file or CLI command to modify update settings.

### What happens if I set autoUpdate to false?

When `autoUpdate` is `false`, OfficeCLI will not spawn the background process that checks GitHub for new releases, nor will it apply any pending updates waiting in the `.update` file. The application runs your current version indefinitely until you manually update or re-enable the flag.