Install

Caplets is pre-1.0. Use the latest CLI and latest docs together.

Requirements

• Node.js 24 or newer for published packages.
• An agent that can use MCP, such as Codex or Claude, or a native integration such as OpenCode or Pi.

Install

Use npx if you only want to try a command without installing globally:

npx caplets install spiritledsoftware/caplets osv

Use the global CLI before running setup. Setup installs or reuses the local Caplets daemon and writes agent configuration that launches caplets attach <local-daemon-url>, so the binary needs to stay on your PATH:

npm install -g caplets
caplets setup
caplets install spiritledsoftware/caplets osv

caplets setup configures supported agent harnesses. It initializes user config, health-checks the daemon before writing agent config, and uses daemon-backed attach/native clients so backend execution keeps the full Caplets environment. The OSV Caplet is the recommended first install because it is public and does not require credentials.

Install lockfiles and updates

Successful installs write a lockfile so the same Caplets can be restored or updated later. Project installs write ./.caplets.lock.json. Global installs write caplets.lock.json under the Caplets state directory, such as ~/.local/state/caplets/caplets.lock.json on Linux.

Restore the Caplets recorded in the selected lockfile with no source argument:

caplets install
caplets install --global

Update every tracked Caplet, or only named Caplets:

caplets update
caplets update sentry github

Install, restore, and update refuse to overwrite local edits unless you pass --force. Use --json when a script needs per-entry statuses and machine-readable errors.

For public external sources, install, restore, and update also attempt best-effort catalog indexing after the local mutation succeeds. Human output prints a short notice when a public Caplet source may be indexed. JSON output includes per-entry catalogIndexing status values. Indexing failures never block install/update/restore, and private or local sources are skipped with redacted categorical statuses.

Set CAPLETS_DISABLE_CATALOG_INDEXING=1 to skip catalog indexing network requests entirely.

If an installed Caplet references unresolved Vault values, output includes immediate recovery guidance. JSON rows include vaultSetup with recovery commands; human output prints the relevant caplets vault set or caplets vault access grant command.

For explicit remote catalog lifecycle operations, --remote targets the remote machine’s global Caplets root and global lockfile:

caplets install --remote spiritledsoftware/caplets sentry
caplets install --remote
caplets update --remote sentry

Remote project install and update semantics are intentionally separate from this workflow.

Manual MCP setup

Prefer caplets setup for local MCP clients. It uses the supported MCP-client catalog and configures caplets attach <local-daemon-url> after the daemon is healthy. For an explicit client target, run:

caplets setup mcp-client --client codex

If you need to write a config by hand, keep it daemon-backed and secret-free:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["attach", "http://127.0.0.1:5387/"]
    }
  }
}

For an advanced manual fallback where the agent intentionally launches a foreground process instead of attaching to the daemon, configure caplets serve directly:

{
  "mcpServers": {
    "caplets": {
      "command": "caplets",
      "args": ["serve"]
    }
  }
}

Use npx in the command only for temporary foreground experiments; daemon-backed setup expects a stable installed caplets binary on PATH:

{
  "mcpServers": {
    "caplets": {
      "command": "npx",
      "args": ["--yes", "caplets", "serve"]
    }
  }
}

If you need non-default HTTP serving behavior, prefer user config over repeating flags:

{
  "serve": {
    "port": 5487,
    "path": "/caplets",
    "publicOrigins": ["https://caplets.example.com"]
  }
}

These serve defaults are user-only. They are ignored from .caplets/config.json, do not set transport under serve, and are overridden by command flags and environment variables. A daemon restart picks up changed user defaults for daemon fields that were not explicitly set during daemon install. Local caplets setup still uses a credential-free loopback daemon before writing MCP or native integration config.

Check the install

Run the doctor check after setup:

caplets doctor

If you use npx, run:

npx caplets doctor

The output should show the active Caplets paths and any integration checks Caplets can run in this environment. Treat failed rows as setup work, not as agent bugs.

Anonymous telemetry

Caplets collects opt-out anonymous telemetry for product usage and reliability. The first eligible interactive CLI run writes a notice to stderr only, so JSON stdout and MCP protocol output stay clean.

Disable telemetry for one process:

CAPLETS_DISABLE_TELEMETRY=1 caplets serve

Disable it in your user Caplets config:

caplets telemetry disable

Inspect local state with caplets telemetry status. Caplets never collects raw config, prompts, Code Mode code, tool arguments, tool outputs, logs, file paths, URLs, hostnames, Caplet IDs, credentials, tokens, raw environment variables, raw error messages, or unsanitized stack traces.

First agent check

After doctor is clean enough for your integration, ask the agent:

Use Caplets Code Mode to query OSV for npm react 18.2.0. Return package,
version, vulnerability count, and advisory IDs as compact JSON.

The agent should call the visible caplets__code_mode tool. Inside Code Mode it should use an OSV handle such as caplets.osv, discover the package-version query tool, and return a compact result instead of a full raw payload.

If the agent cannot see caplets__code_mode, restart the agent after caplets setup, then use Troubleshooting.