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

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 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 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.

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:

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 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 for updates on the next invocation.

Summary

• OfficeCLI runs a background update check via __update-check__ defined in src/officecli/Program.cs and implemented in 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 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 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, eliminating the startup delay.

Does the install.sh script support pre-configuring auto-update settings?

Yes. The bundled 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}