iOfficeAI/OfficeCLI · error · OfficeCliError

officecli install failed (exit {r.returncode}). Run manually

Error message

officecli install failed (exit {r.returncode}). Run manually:
    irm https://d.officecli.ai/install.ps1 | iex

What it means

Raised by officecli.install() on Windows when the PowerShell installer (irm of the .ps1 mirror with GitHub fallback, piped to iex) exits with a non-zero return code. The SDK streams installer output to the user and, on failure, reports the exit code and the manual irm | iex command to run.

Source

Thrown at sdk/python/officecli.py:598

    unix, install.ps1 on Windows. Reuses officecli's own installers (platform
    detection + checksum + ~/.local/bin or %LOCALAPPDATA%\\OfficeCLI), rather than
    reimplementing download logic that would drift from upstream.

    Called automatically by open()/create() when the CLI is missing (pass
    auto_install=False to disable), and exposed directly as `python -m officecli
    install`. Returns None on success; raises OfficeCliError on failure. Output is
    NOT captured, so the installer's progress and checksum lines stream to the
    user."""
    if _IS_WIN:
        print(f"Installing officecli via {_INSTALL_PS1_MIRROR} (github fallback) ...", file=sys.stderr)
        # Windows PowerShell (powershell.exe) ships with the OS; -ExecutionPolicy
        # Bypass lets the remote script run without changing machine policy. Fetch
        # the script mirror-first, github fallback, then run it.
        ps = (f"$s = try {{ irm '{_INSTALL_PS1_MIRROR}' }} "
              f"catch {{ irm '{_INSTALL_PS1_GITHUB}' }}; $s | iex")
        r = subprocess.run(["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", ps])
        if r.returncode != 0:
            raise OfficeCliError(r.returncode,
                f"officecli install failed (exit {r.returncode}). Run manually:\n"
                f"    irm {_INSTALL_PS1_MIRROR} | iex")
        return None
    print(f"Installing officecli via {_INSTALL_SH_MIRROR} (github fallback) ...", file=sys.stderr)
    # (curl mirror || curl github) | bash — the subshell emits whichever fetch
    # succeeds; the group keeps the pipe bound to the whole fallback. Output is
    # NOT captured, so progress and checksum lines stream to the user.
    sh = f"(curl -fsSL {_INSTALL_SH_MIRROR} 2>/dev/null || curl -fsSL {_INSTALL_SH_GITHUB}) | bash"
    r = subprocess.run(["bash", "-c", sh])
    if r.returncode != 0:
        raise OfficeCliError(r.returncode,
            f"officecli install failed (exit {r.returncode}). Run manually:\n"
            f"    curl -fsSL {_INSTALL_SH_MIRROR} | bash")
    return None


# Advertised surface = the command shell + its error. pipe_paths stays importable
# (officecli.pipe_paths) as a debug helper but isn't part of the command API.

View on GitHub (pinned to 1ced45e900)

Solutions

Run the manual command: irm https://d.officecli.ai/install.ps1 | iex in a PowerShell window to see full output.
Check network/proxy access to d.officecli.ai and the GitHub raw mirror.
If ExecutionPolicy blocks it, run from an elevated shell or adjust policy as your admin permits.

Example fix

# before — installer failed non-interactively
officecli.install()
# after — run manually in PowerShell to see errors
# PS> irm https://d.officecli.ai/install.ps1 | iex

Defensive patterns

Strategy: fallback

Validate before calling

null

Type guard

null

Try / catch

import subprocess, officecli

try:
    officecli.install()
except officecli.OfficeCliError as e:
    # fall back to running the manual PowerShell command with full output
    subprocess.run(['powershell', '-NoProfile', '-ExecutionPolicy', 'Bypass',
                    '-Command', 'irm https://d.officecli.ai/install.ps1 | iex'])

Prevention

On install failure, run irm https://d.officecli.ai/install.ps1 | iex manually to see full output.
Confirm network/proxy access to d.officecli.ai and the GitHub raw mirror.
Run from a shell with adequate PowerShell execution rights.

When it happens

Trigger: Running officecli.install() on Windows where PowerShell execution fails: network blocked from fetching the script, ExecutionPolicy conflict, mirror and GitHub both unreachable, or the installer script itself errors.

Common situations: Corporate proxy/firewall blocking irm; restricted PowerShell execution context; transient mirror outage; partial download/checksum failure.

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/4bef03f2346b66f3. Report an issue: GitHub.