Clapilot Code CLI

clapilot-code is a standalone coding-agent CLI for macOS and Linux machines that can reach a Clapilot instance. The model runs through that instance's inference gateway, while file reads, edits, directory listings, and shell commands execute locally in the directory where you launch the CLI. The instance does not execute those local tools.

The CLI is a single JavaScript file, requires Node.js 20 or newer, and has no package dependencies. The distribution and inference routes exist only while Developer mode is enabled on the instance.

Install

Run the instance-served installer:

curl -fsSL https://your-instance.example/api/clapilot-code/install | bash

The installer writes the executable to ~/.clapilot-code/bin/clapilot-code.mjs. It links clapilot-code into /usr/local/bin when that directory is writable; otherwise it uses ~/.local/bin and prints a PATH instruction when needed.

Login and API-key scope

An instance admin creates an API key in Settings → API keys with the inference:execute scope. Add tools:execute to the same key when the CLI should use the instance's curated coding tools. Login validates the key against the model catalog, stores it locally, and selects the first tool-capable model as the default:

clapilot-code login --base-url https://your-instance.example

The API key prompt is hidden. Configuration is stored in ~/.clapilot-code/config.json with file mode 0600; the containing directory uses mode 0700. Do not share this file.

Commands

List available models. [tools] identifies models that support the local agent loop, and [default] shows the current default:

clapilot-code models

Run one task in the current directory:

clapilot-code exec "Inspect the project, fix the failing test, and verify the result"
clapilot-code exec --model provider/model-id --max-steps 20 "Explain the build failure"
clapilot-code exec --cd /srv/project "Update the README"

exec and exec resume accept --output-format stream-json (since CLI 0.3.1) to emit one JSON event per stdout line — session.started, item entries for assistant messages and tool calls (with arguments and bounded output), and a final result — instead of human-readable text. The Agent Orchestrator remote runner uses this automatically so remote Clapilot Code jobs render typed conversation and tool rows in the web and Apple clients; errors continue to go to stderr in both formats.

Resume a saved session by its ID. The saved working directory is reused when it still exists; --cd overrides it:

clapilot-code exec resume <session-id> "Continue and run the focused tests"
clapilot-code exec resume --cd /new/project/path <session-id> "Continue here"

Use --session FILE_OR_ID on a regular exec to continue an existing session or create a named session. A path ending in .jsonl creates or uses that exact file; a bare ID resolves inside the session directory.

Start an interactive session in the current directory. Running clapilot-code with no command does the same thing, and a bare quoted argument becomes the opening prompt:

clapilot-code
clapilot-code "explain this repository"
clapilot-code chat --model provider/model-id

In a terminal, the interactive session opens a full-screen TUI (since CLI 0.4.0) in the style of Claude Code and Codex: a welcome banner with the Clapilot logo, version, model, instance, directory, and tool summary; a header with model, working directory, and session id; a scrolling transcript with your prompts, streamed assistant prose (basic markdown: headings, lists, inline code, fenced code blocks), and tool rows that show a spinner while running, then a ✔/✖ status and a short output preview; model reasoning — whether streamed as reasoning_content or embedded as <think>…</think> in the answer — shows as an animated “Thinking…” section with its latest lines and collapses to “Thought for Ns” once the answer starts; a bordered multi-line input box at the bottom; and a status line with the current step while the model works. Assistant tokens stream in live over the instance gateway's SSE endpoint. The TUI is hand-rolled ANSI inside the same single dependency-free file — no framework is bundled, so the instance-served distribution and self-update stay unchanged. On exit the transcript is replayed into the normal terminal scrollback and the session id is printed for exec resume.

Keys: Enter sends, Ctrl+J / Alt+Enter / \ + Enter insert a newline, ↑/↓ browse prompt history (or move between input lines), Tab completes a slash command, PgUp/PgDn scroll the transcript, Esc interrupts the running turn (or clears the input), Ctrl+C interrupts, clears, or exits when pressed twice, Ctrl+L clears the transcript view, and Ctrl+D exits on an empty input.

Slash commands: /help, /model [id] (no argument opens an arrow-key picker of tool-capable models), /models, /new, /sessions (recent sessions), /resume <id|#> (continue a saved session in place), /cd <dir>, /steps <n>, /status, /clear, and /exit.

clapilot-code chat --inline keeps the terminal's normal line-by-line flow instead of the full-screen view: a compact banner, a spinner while thinking, tool rows that update in place with duration and a short output preview, styled assistant text, and the /help, /model <id>, /models, /session, /clear, /exit commands. When stdout is not a terminal, NO_COLOR is set, or TERM=dumb, the session falls back to the plain-text output unchanged, so scripted and piped use keeps working.

Instance tools

When the configured API key also grants tools:execute, each agent-loop process loads the instance's personal_read catalog once (GET /api/v1/tools/catalog?profile=personal_read, since CLI 0.4.2; older instances answer with the coding core). The model can then use creator-bound memory, context, Knowledge, Learning, web-search, session/status, and scoped task-comment tools, plus read-only access to your emails and drafts, calendar events, task boards and tasks, notes, documents, and wiki pages — so "what are my latest emails" is one audited emails_list_messages call on the instance. These tools execute on the Clapilot instance as the user who created the API key; shell commands and file operations continue to run only on the local machine. Mutating tools (sending mail, creating events, deleting documents) are intentionally not offered to the CLI.

The system prompt draws a hard boundary around that: when no tool covers a request, the agent must say which capability is missing and stop — it must never look for credentials (.env, database URLs, OAuth/API tokens), query databases or third-party APIs directly, enter Clapilot infrastructure (docker exec, psql, ssh), or drive desktop/mail apps and browsers to reach your accounts. In the interactive TUI, shell commands that match those patterns (plus sudo, rm -rf, osascript/open -a, authenticated curl, cloud CLIs) pause the turn with an Allow once / Deny prompt; a denied command is reported to the model as a decision it must not work around. exec runs (detached remote jobs) rely on the prompt boundary alone so they stay unattended.

If the key does not grant tools:execute or the catalog cannot be reached, the CLI prints one hint and continues with local tools only. Pass --no-instance-tools to exec, exec resume, chat, or a bare invocation to force local-only operation without requesting the catalog:

clapilot-code exec --no-instance-tools "Inspect this repository without instance context"
clapilot-code chat --no-instance-tools
clapilot-code --no-instance-tools "explain this repository"

Sessions

Default sessions live at ~/.clapilot-code/sessions/<uuid>.jsonl. The first JSON line contains session metadata including the ID, timestamps, working directory, model, and title. Following lines contain user, assistant, and tool messages in their original order. System instructions and the API key are never written to session files.

When the same machine runs the Agent Orchestrator Node remote runner codex-remote-runner/0.2.4 or newer, these sessions appear alongside Codex CLI sessions in the web module's Remote Agents tab with a Clapilot Code harness label. Opening a session requests its transcript from the runner, and the web composer resumes it on that machine through clapilot-code exec resume with its saved working directory.

Remote jobs

Machines running the Agent Orchestrator remote runner codex-remote-runner/0.2.7 or newer can be provisioned from the instance instead of installing manually: Settings -> Agent Orchestrator offers a per-machine Install Clapilot Code button (and an auto-provision toggle for newly connecting runners) that ships the CLI over the runner's own pull channel, creates a dedicated revocable inference:execute API key, and writes the login configuration — no Developer mode and no shell access to the machine required.

With runner codex-remote-runner/0.2.6 or newer, a machine whose clapilot-code CLI is installed and logged in advertises the clapilot-code capability to the Agent Orchestrator. The module's + New Agent composer can then start fresh detached jobs with the Clapilot Code harness on that machine: the runner clones the selected repository into a per-job worktree and runs clapilot-code exec (with --model when a catalog model was chosen). Follow-ups reuse the same remote workspace. With CLI 0.3.1+ and runner 0.2.9+ the run uses --output-format stream-json, so assistant messages and tool calls render as typed conversation rows; older CLIs keep plain-text job logs.

Update

Update the installed executable from the configured instance:

clapilot-code update

Before replacing itself atomically, the CLI requires the download to declare a semantic CLI_VERSION and pass node --check.

Limitations

• Agent runs require a model marked as tool-capable by GET /api/v1/inference/models. Subscription/CLI-bridge transports that reject client-supplied tools cannot run the local coding loop.
• The CLI supports text prompts only. Attachments and image inputs are not supported.
• Shell commands and file mutations run with the permissions of the local user. Review the task and working directory before starting a run.
• Instance tools require the high-privilege tools:execute scope and run with the permissions of the API key's creator. Use a dedicated expiring key and opt out with --no-instance-tools when instance context is not needed.
• Sessions retain full history and are not compacted by the CLI; very long sessions can eventually exceed a model's context window.