# How to Configure OfficeCLI Auto-Update Behavior Using Config Commands and Environment Variables

> Control OfficeCLI auto-update checks with config commands or environment variables. Permanently disable updates or skip them for a single run.

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

---

**You can permanently toggle OfficeCLI's background update checks using `officecli config autoUpdate true|false`, or temporarily skip them for a single invocation by setting the `OFFICECLI_SKIP_UPDATE=1` environment variable.**

OfficeCLI, maintained in the iOfficeAI/OfficeCLI repository, automatically queries GitHub for new releases on startup to ensure users run the latest version. Learning how to configure OfficeCLI auto-update behavior is critical for CI/CD environments where deterministic builds are required or in air-gapped networks where external calls must be avoided.

## Where Auto-Update Settings Are Stored

According to the source code in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs) (line 30), OfficeCLI persists its settings in a JSON file located at `~/.officecli/config.json`. This file contains an **AutoUpdate** boolean flag that defaults to `true`, meaning the CLI will attempt to contact GitHub on startup unless explicitly configured otherwise.

## Persistent Configuration Using the `config` Command

To change auto-update behavior permanently, use the built-in configuration command. The parsing logic for `officecli config <key> [value]` resides in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 444-492), where the CLI validates the key name and writes the updated value to disk.

### Disabling Auto-Updates

Run the following to write `AutoUpdate: false` to your config file and prevent future background checks:

```bash
officecli config autoUpdate false

```

### Re-enabling Auto-Updates

To restore automatic version checking, set the flag back to `true`:

```bash
officecli config autoUpdate true

```

## One-Time Overrides with Environment Variables

For temporary suppression—such as in automated scripts or CI jobs—OfficeCLI respects the **OFFICECLI_SKIP_UPDATE** environment variable. As implemented in [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) (line 268), setting this variable to `1` causes an early exit from the update routine for that specific invocation, regardless of the stored config value.

Use this method when you cannot modify the persistent config but need to eliminate network calls for a single run:

```bash
OFFICECLI_SKIP_UPDATE=1 officecli get mydoc.docx some/path

```

In PowerShell, set the variable for the current session:

```powershell
$env:OFFICECLI_SKIP_UPDATE = '1'
officecli get mydoc.docx some/path

```

## Core Update Logic Implementation

The decision to check for updates occurs in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 66-88). The code first verifies that `config.AutoUpdate` is enabled, then compares the `LastUpdateCheck` timestamp against `CheckIntervalHours` to enforce a time-based throttle.

```csharp
// Core decision flow from UpdateChecker.cs (lines 66-88)
if (config.AutoUpdate) {
    if (!config.LastUpdateCheck.HasValue ||
        (DateTime.UtcNow - config.LastUpdateCheck.Value).TotalHours >= CheckIntervalHours) {
        // Proceed to contact GitHub API for new releases
    }
}

```

This implementation ensures the CLI respects both the boolean flag and the elapsed time since the previous check, preventing excessive API requests.

## Programmatic Configuration (Advanced)

For developers extending OfficeCLI, you can manipulate the configuration object directly using the `UpdateChecker` class methods:

```csharp
var cfg = OfficeCLI.Core.UpdateChecker.LoadConfig();
cfg.AutoUpdate = false;
OfficeCLI.Core.UpdateChecker.SaveConfig(cfg);

```

This accesses the same `AppConfig` definition and persistence layer used by the CLI's built-in commands, ensuring consistency with the JSON schema.

## Summary

- **Persistent control**: Use `officecli config autoUpdate false` to write `"AutoUpdate": false` to `~/.officecli/config.json`, or `true` to re-enable background checks.
- **Temporary bypass**: Set `OFFICECLI_SKIP_UPDATE=1` before invoking `officecli` to skip the check for a single run, as handled in [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs) (line 268).
- **Storage location**: Configuration lives in `~/.officecli/config.json` by default, defined in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (line 30).
- **Check interval**: The logic in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 66-88) combines the `AutoUpdate` flag with a `CheckIntervalHours` throttle to regulate GitHub API calls.

## Frequently Asked Questions

### What is the default auto-update behavior in OfficeCLI?

By default, the `AutoUpdate` property in `~/.officecli/config.json` is set to `true`. The application checks for new releases according to the interval logic defined in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs), provided the `OFFICECLI_SKIP_UPDATE` environment variable is not set.

### Can I disable auto-updates without using the command line?

Yes. Since the configuration is stored as plain JSON in `~/.officecli/config.json`, you can manually edit this file and set `"AutoUpdate": false`. However, using `officecli config autoUpdate false` is recommended to ensure proper schema validation as implemented in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 444-492).

### Will setting OFFICECLI_SKIP_UPDATE permanently change my configuration?

No. The environment variable acts as a runtime override only. As seen in [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) (line 268), it causes an early return from the update routine without persisting any changes to disk. Your [`config.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/config.json) retains its previous `AutoUpdate` value for subsequent executions where the variable is unset.

### How frequently does OfficeCLI check for updates when enabled?

The source code in [`UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/UpdateChecker.cs) (lines 66-88) enforces a time-based interval using `CheckIntervalHours`. The CLI compares the current UTC time against `config.LastUpdateCheck` and only contacts GitHub if the elapsed duration exceeds this threshold, preventing checks on every single execution.