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"

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

Enter one request per line. Type exit or press Ctrl-C to finish. A Ctrl-C during a model turn aborts the request and keeps all messages written so far.

Instance tools

When the configured API key also grants tools:execute, each agent-loop process loads the instance's curated coding-core catalog once. The model can then use creator-bound memory, context, Knowledge, Learning, web-search, session/status, and scoped task-comment tools. 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.

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.

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.