xcsh

An AI-native terminal assistant for engineering, automation, and reviewable F5 Distributed Cloud workflows.

xcsh is an independent open-source project derived from pi/pi-mono, specialized for F5 Distributed Cloud workflows; it is not an F5 product.

Install xcsh

Universal installer for macOS and Linux.

curl -fsSL https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.sh | sh

It installs the latest prebuilt release into ~/.local/bin. Need a managed or platform-specific channel? Compare the installation options.

What xcsh helps you do

Agentic terminal work

Run interactive or print-mode prompts, inspect files, use tools, and keep durable session history when the task needs it. Learn the agent loop.

Reviewable F5 Distributed Cloud workflows

Discover schemas, validate manifests, and inspect proposed differences before an authorized resource change. Use resource workflows.

Extensible automation

Add headless workflows, custom tools, skills, plugins, or MCP servers when built-in commands are not enough. Automate and extend.

These workflows start with a working executable; choose another channel only when the universal installer is not the right fit.

Installation options

Use one channel for install and upgrades. Mixing package-manager and standalone installations can leave more than one xcsh on PATH; the universal installer above is not repeated here.

macOS

Install the signed and notarized macOS archive through the Homebrew cask. The cask preserves the released executable and native addon byte for byte and does not require sudo:

brew install --cask f5-sales-demo/tap/xcsh

Upgrade or remove

Upgrade with brew upgrade --cask xcsh. Remove the cask with brew uninstall --cask xcsh. These commands preserve configuration, credentials, and sessions under ~/.xcsh.

Clean break from the historical package cask

Before installing this cask on a Mac that received an earlier xcsh package, uninstall both old Homebrew entries (brew uninstall --formula xcsh and brew uninstall --cask xcsh). Then have MDM forget the com.f5.xcsh receipt and remove only the package-owned /usr/local/bin/xcsh and /Library/Application Support/xcsh payload. Do not remove ~/.xcsh. The signed and stapled .pkg release assets remain available only for direct MDM deployment.

Ubuntu or Debian

The signed apt repository supports amd64 and arm64 and follows normal system upgrades:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://f5-sales-demo.github.io/apt-repo/f5xc-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/f5xc-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/f5xc-archive-keyring.gpg] https://f5-sales-demo.github.io/apt-repo stable main" \
  | sudo tee /etc/apt/sources.list.d/f5xc.list
sudo apt-get update && sudo apt-get install xcsh

Upgrade or remove

Upgrade with sudo apt-get update && sudo apt-get install --only-upgrade xcsh. Remove the package with sudo apt-get remove xcsh.

Windows

Run the PowerShell installer, then restart the terminal so its user PATH refreshes:

irm https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.ps1 | iex

It installs xcsh.exe and native add-ons to %LOCALAPPDATA%\\xcsh. Bash is required for tool-backed sessions. Install Git for Windows, WSL, Cygwin, or MSYS2; set shellPath in %USERPROFILE%\\.xcsh\\agent\\settings.json when Bash is elsewhere.

Upgrade or remove

Re-run the installer to upgrade. To uninstall, remove %LOCALAPPDATA%\\xcsh and its entry from the user PATH.

Container

Docker and Podman use the same multi-architecture image. Pin a release tag, resolve its digest for deployment, and mount only the workspace and state required by the task:

docker pull ghcr.io/f5-sales-demo/xcsh:vX.Y.Z
docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/f5-sales-demo/xcsh:vX.Y.Z
docker run --rm ghcr.io/f5-sales-demo/xcsh@sha256:<digest> --version

Podman accepts the same pull, inspect, and run arguments. Pass provider credentials at runtime through a secret manager or environment file; never bake them into an image layer.

Upgrade or remove

Pull a newer pinned tag to upgrade. Remove an unused image with docker image rm IMAGE or podman image rm IMAGE.

Packages and source

Use a JavaScript package or a source/ref install when you need a toolchain or an unreleased ref. Source installs require Git and Bun 1.4.2 or newer:

bun install --global @f5-sales-demo/xcsh
npm install --global @f5-sales-demo/xcsh
curl -fsSL https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.sh \
  | sh -s -- --source --ref vX.Y.Z

The explicit --source and --ref arguments select a reproducible source install.

Upgrade or remove

Upgrade with bun update --global @f5-sales-demo/xcsh or npm update --global @f5-sales-demo/xcsh. Remove the package with bun remove --global @f5-sales-demo/xcsh or npm uninstall --global @f5-sales-demo/xcsh; re-run the source command at a new ref to replace that channel.

Whichever installation channel you choose, open xcsh next.

Verify installation

Start the interactive terminal UI:

xcsh

When the xcsh prompt appears, connect a model provider from inside the TUI.

Authenticate a provider

At the xcsh prompt, open the provider picker:

/login

Choose a provider and follow its sign-in flow. You can also enter /login PROVIDER to open a known provider directly. Keep credentials in the provider-supported environment or subscription login—never in a prompt or committed settings file. See model authentication for provider-specific options.

GPT-6 Luna and Sol use a 272K-token context window by default for ChatGPT subscription sessions. To opt in to their published 1.05M-token window, open /settings, select Providers, and enable OpenAI Codex Maximum Context. OpenAI applies higher token pricing to requests above 272K. Internal LiteLLM GPT routes use the same 272K default independently; enable LiteLLM Maximum Context to opt those routes into their verified 1.05M-token window.

After sign-in selects a model, stay in the TUI and send a small first prompt.

Quickstart

At the xcsh prompt, enter:

Reply with only: xcsh is ready

A matching response confirms the installation, provider, and selected model are working together without granting a tool any file or network side effect. If it fails, verify the active executable with command -v xcsh, reopen /login, and confirm the selected model is available to that account. Next, learn the interactive TUI or choose a context and namespace before an authorized F5 Distributed Cloud change.

From here, continue with the documentation path that matches your goal.

Explore by goal

Choose the goal closest to your next task; each path starts from the verified installation above.

Use xcsh

F5 Distributed Cloud

Configure and secure

Automate and extend

Integrations and deployment

Reference and troubleshooting