CAIPE CLI

Terminal client for CAIPE: chat with dynamic agents, manage skills, and run headless prompts against a remote CAIPE UI / BFF.

Install CAIPE CLI:

curl -fsSL https://raw.githubusercontent.com/cnoe-io/caipe-cli/main/install.sh | sh

The installer downloads the latest verified release and asks where to place the caipe launcher. Press Enter for ~/.local/bin (recommended, no password), choose ~/.bin, or stage a launcher for an explicit system-wide install. The web-fetched script never invokes sudo or reads a password.

Point at your CAIPE deployment, sign in, chat:

caipe config set server.url https://caipe.example.com
caipe config set auth.url https://idp.caipe.example.com/realms/caipe
caipe auth login
caipe agents list
caipe chat --agent '<id-from-agents-list>'

Type messages at the ❯ prompt. / for commands, Ctrl+O to pick an agent, Ctrl+D to exit.

Prompt line editing is implemented in-tree (src/chat/line-edit.ts, Apache-2.0): common bash/emacs keys (Ctrl+A/E/K/U/W/Y, Alt+b/f/d, Ctrl+R history search, etc.). It does not use GNU Readline or other GPL line-editing libraries.

Other host (UI serves OAuth on the same URL): set only server.url, then caipe auth login and caipe chat.

• macOS or Linux on arm64 or x64
• curl and Node.js 20 or newer
• A reachable CAIPE deployment (API + OAuth)

Optional: keytar only if you set auth.credential-storage to keychain.

curl -fsSL https://raw.githubusercontent.com/cnoe-io/caipe-cli/main/install.sh | sh

The installer asks you to choose:

1. ~/.local/bin — recommended, no password
2. ~/.bin — user-owned alternative, no password
3. /usr/local/bin — stages the launcher and prints separate review/install commands

Press Enter to accept option 1. In a non-interactive environment, option 1 is selected automatically. Then verify with caipe --version. If the selected directory is not already on PATH, the installer prints the exact command to add it.

Automation can bypass the prompt with CAIPE_INSTALL_DIR. For example, choose the user-owned ~/.bin directory without a password:

curl -fsSL https://raw.githubusercontent.com/cnoe-io/caipe-cli/main/install.sh \
  | CAIPE_INSTALL_DIR="$HOME/.bin" sh

Choose a system-wide directory explicitly:

curl -fsSL https://raw.githubusercontent.com/cnoe-io/caipe-cli/main/install.sh \
  | CAIPE_INSTALL_DIR=/usr/local/bin sh

The web installer downloads and verifies the binary, stages the launcher under ~/.local/share/caipe, and stops. It never invokes sudo. Review the staged launcher, then separately run the exact sudo mkdir and sudo install commands it prints.

In every case, CAIPE_INSTALL_DIR controls only the small launcher on PATH; the platform binary is stored under ~/.local/share/caipe by default.

The installer downloads the latest multi-architecture GitHub release and verifies its SHA-256 checksum. Pin a release when reproducibility matters:

curl -fsSL https://raw.githubusercontent.com/cnoe-io/caipe-cli/main/install.sh \
  | CAIPE_VERSION=0.2.22 sh

The npm package is not published yet; use install.sh until it is available.

Interactive chat checks GitHub Releases at most once every 24 hours. Known binary installs update automatically; other install types receive one notification per release. Update manually:

caipe update --check    # inspect only
caipe update            # download, verify, smoke-test, and install

Downloaded binaries must match caipe-checksums.txt and pass --version before atomically replacing the installed binary. npm-managed installations delegate an explicit update to npm. Verified binary updates install automatically by default:

caipe config set updates.mode notify  # auto (default), notify, or off

Source or unknown launchers fall back to a notification and an actionable manual update command. Set CAIPE_NO_UPDATE_CHECK=1 for a one-off invocation.

Every commit to main is released after the full CI workflow succeeds. The release workflow creates the next patch tag, publishes checksummed binaries, signs them with cosign, and publishes the matching npm packages.

git clone https://github.com/cnoe-io/caipe-cli.git
cd caipe-cli
bun install
npm run compile          # native binary → dist/caipe
./dist/caipe --version

For a development checkout, run npm link or use node bin/caipe.cjs rather than copying the compiled binary into PATH.

Compile note: npm run compile uses Bun with keytar external so the default encrypted-file credential store works without building native modules. If you use the keychain backend:

npm install keytar
npm rebuild keytar
caipe config set auth.credential-storage keychain

npm run lint
npm test

The Publish caipe CLI GitHub Actions workflow runs for semantic-version tags. It verifies the source, builds and smoke-tests all four supported binaries, publishes a GitHub release with checksums and keyless cosign signatures, then publishes the four platform packages and the top-level caipe npm package.

This distribution path is for maintainers and is not a working user install method until the first tagged workflow completes successfully.

git tag 0.2.22
git push origin 0.2.22

The GitHub npm-publish environment must provide an NPM_TOKEN secret with permission to publish caipe and the four caipe-<os>-<arch> packages. Prerelease tags such as 0.2.22-rc.1 publish to npm's next dist-tag; stable versions publish to latest.

Settings live in ~/.config/caipe/settings.json.

When the UI exposes OAuth and /.well-known/agent.json on the same host:

caipe config set server.url https://your-caipe.example.com
caipe auth login
caipe agents list
caipe config set agent.default agent-sre   # id from agents list; optional
caipe chat

config set server.url also sets auth.url to the same value.

On some deployments the BFF may not expose /oauth/authorize yet. Point the API at CAIPE and OAuth at Keycloak:

caipe config set server.url https://caipe.example.com
caipe config set auth.url https://idp.caipe.example.com/realms/caipe
rm -f ~/.config/caipe/agent-config.json
caipe auth logout    # if you have stale tokens
caipe auth login

Optional IdP shortcut (e.g. Duo SSO):

caipe config set auth.idp-hint duo-sso
# or: export CAIPE_IDP_HINT=duo-sso

caipe                  # same as caipe chat
caipe chat --agent my-agent

In the REPL:

• / — slash commands (/agents, /skills, /login, /help, /exit, …)
• !cmd — run a shell command and inject output
• Esc — abort streaming

caipe agents list
caipe agents info <name>
caipe skills list
caipe skills install <name>

caipe chat --headless --prompt "Summarize open incidents"
caipe chat --headless --prompt-file question.txt --output json
caipe chat --headless --token "$JWT" --prompt "health check"

caipe auth status
caipe auth login --force
caipe auth login              # PKCE in isolated Chrome/Chromium (default)
caipe auth login --system-browser   # use default browser profile (can affect Web UI)
caipe auth login --device      # device code flow
caipe auth login --manual      # paste authorization code
caipe auth logout

OAuth browser: By default the CLI opens Chrome/Chromium with a temporary profile so logging in does not overwrite cookies for an open caipe-ui tab. Set CAIPE_CHROMIUM_PATH if Chrome is non-standard. CAIPE_AUTH_BROWSER=system restores the old behavior. CAIPE_AUTH_HEADLESS=1 uses headless mode (often breaks MFA).

Non-interactive commands talk to the CAIPE RAG REST API and always print JSON to stdout (errors as JSON on stderr).

caipe config set kb.url https://your-kb-api.example.com   # or export CAIPE_KB_URL
caipe auth login   # or export CAIPE_TOKEN / client credentials for CI

caipe kb user info
caipe kb datasources list
caipe kb documents list <datasource-id> --limit 50
caipe kb query --query "how do I deploy SSE?"
caipe kb chunk get '<chunk-id>'

caipe kb ingest url --url https://docs.example.com/
caipe kb ingest file ./README.md ./guide.pdf --owner-team-slug my-team
caipe kb job get <job-id>

Shared flags on caipe kb: --kb-url, --token, --tenant-id (or CAIPE_TENANT_ID).

Rich terminal output (interactive chat): Markdown is rendered with react-markdown + remark-gfm as native Ink components (no ANSI markdown strings). Diffs use Ink colors. Block streaming caches completed sections in <Static>; the active tail updates in place. Tool runs show in the footer. Chat uses the alternate screen unless CAIPE_NO_ALT_SCREEN=1 or CAIPE_PLAIN_TERMINAL=1. Legacy plain streaming: CAIPE_STREAM_PLAIN=1.

Default credentials: encrypted file at ~/.config/caipe/credentials.enc (AES-256-GCM, machine-derived key). No Keychain prompts unless you opt into keychain.

Global flags: --agent, --url, --json, --no-color, -v / --version.

caipe-cli/
  src/           TypeScript source
  bin/caipe.cjs  npm/npx launcher
  dist/          compile output (gitignored)
  tests/         Vitest
  setup-caipe-cli.sh
  install.sh

Older BFFs only allow webui, slack, and webex. The CLI tries slack first, then cli, when creating conversations. Rebuild from latest main if you still see a cli-only error.

Set server.url to the UI/BFF, then run caipe config discover. Discovery tries, in order: /.well-known/agent.json, OIDC metadata on the BFF host, then deployment-specific hostname heuristics. Override the realm with CAIPE_AUTH_REALM. You can still set auth.url manually (for example, https://idp.caipe.example.com/realms/caipe).

Apache-2.0