# Configuring OfficeCLI Auto-Update for Air-Gapped Environments: Complete Guide

> Learn to configure OfficeCLI auto-update for air-gapped environments. Prevent network checks by disabling updates via environment variable or config file.

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

---

**Disable OfficeCLI auto-updates by setting the `OFFICECLI_DISABLE_AUTO_UPDATE=1` environment variable or adding `"autoUpdate": false` to `~/.officecli/config.json` to prevent background network checks in offline environments.**

OfficeCLI includes a built-in auto-update mechanism that spawns a background process on every invocation to check GitHub releases for newer binaries. For **air-gapped environments** where network access is restricted or prohibited, this behavior causes unnecessary delays and potential security concerns. According to the iOfficeAI/OfficeCLI source code, you can completely suppress this feature using environment variables or configuration files without modifying the binary itself.

## How the Auto-Update Mechanism Works

The auto-update system operates through two key components in the codebase:

In [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) at line 27, the CLI parses command-line arguments and launches a hidden `__update-check__` sub-process. This internal command triggers the update logic without blocking the main CLI execution.

The actual implementation resides in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs) at line 21, where a separate process contacts the GitHub release feed to determine if a newer binary is available. If found, the system attempts to download and replace the current executable automatically.

In isolated networks, this check consistently fails and wastes system resources, making suppression essential for production deployments.

## Method 1: Disable Updates via Environment Variable

The fastest way to disable auto-updates is setting the **`OFFICECLI_DISABLE_AUTO_UPDATE`** environment variable. When this variable contains any non-empty value, the startup sequence detects it and skips the background update process entirely.

```bash
export OFFICECLI_DISABLE_AUTO_UPDATE=1
officecli docx create report.docx

```

This method is ideal for temporary testing, CI/CD pipelines, or containerized environments where you want to guarantee no network calls without persisting configuration files.

## Method 2: Disable Updates via Configuration File

For permanent air-gapped deployments, use the user-wide configuration file. Create or edit **`~/.officecli/config.json`** and set the `autoUpdate` flag to `false`:

```bash
mkdir -p ~/.officecli
cat > ~/.officecli/config.json <<'EOF'
{
  "autoUpdate": false
}
EOF

```

The configuration loader reads this flag during initialization and prevents the updater from being scheduled. This approach persists across system reboots and applies to all OfficeCLI invocations for the user account.

## Step-by-Step Deployment for Air-Gapped Systems

Follow these steps to prepare OfficeCLI for reliable offline operation:

1. **Install OfficeCLI** using the standard [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) script. You can customize this script to pre-seed the configuration with `"autoUpdate": false` during mass deployments.
2. **Choose your disable method**:
   - Set `export OFFICECLI_DISABLE_AUTO_UPDATE=1` in the shell profile (e.g., `.bashrc` or `.zshrc`)
   - Or create `~/.officecli/config.json` with the JSON content shown above
3. **Verify the configuration** by running `officecli`—the background process should not spawn, and the resident-mode flush logic continues to work unchanged.

Both methods work identically across Linux, macOS, and Windows platforms, and require no binary modification or firewall rules.

## Re-enabling Automatic Updates

When the system returns to a networked environment, reverse your chosen method:

- **Environment variable**: Run `unset OFFICECLI_DISABLE_AUTO_UPDATE` or remove the export from shell profiles
- **Configuration file**: Change `"autoUpdate": false` to `"autoUpdate": true` in `~/.officecli/config.json`

The CLI will resume checking [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs) for updates on the next invocation.

## Summary

- OfficeCLI runs a background update check via `__update-check__` defined in [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) and implemented in [`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs)
- Air-gapped environments must disable this feature to prevent failed network requests and performance delays
- **Set `OFFICECLI_DISABLE_AUTO_UPDATE=1`** for immediate, session-based suppression
- **Create `~/.officecli/config.json`** with `"autoUpdate": false` for permanent, user-wide configuration
- Both methods are cross-platform and require no binary modifications

## Frequently Asked Questions

### Will disabling auto-updates affect OfficeCLI document generation features?

No. Disabling the auto-update mechanism only prevents the background process from checking GitHub releases. All core document automation capabilities—including creating DOCX files and processing templates—continue to function normally without network connectivity, and the resident-mode flush logic remains unaffected.

### Can I disable auto-updates system-wide for all users?

While the configuration file method applies per-user (`~/.officecli/config.json`), you can achieve system-wide suppression by setting the `OFFICECLI_DISABLE_AUTO_UPDATE` environment variable in the global shell profile (e.g., [`/etc/profile.d/officecli.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main//etc/profile.d/officecli.sh) on Linux) or through system environment variables on Windows. The CLI checks this variable before any user-specific configuration.

### Why does OfficeCLI freeze briefly on startup in air-gapped environments?

The freeze occurs because [`Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/UpdateChecker.cs) attempts to contact the GitHub release feed and waits for a connection timeout. Setting `OFFICECLI_DISABLE_AUTO_UPDATE=1` or the config file flag completely skips this network request in [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs), eliminating the startup delay.

### Does the [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) script support pre-configuring auto-update settings?

Yes. The bundled [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) script can be customized to write the default config file with `"autoUpdate": false` during installation. This is useful for enterprise deployments where you want to provision air-gapped machines without manual configuration steps.