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 writes agent configuration that launches caplets serve, 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. 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

If your client does not support caplets setup, or if you are avoiding a global install, add Caplets as a stdio MCP server:

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

Use npx in the command if you did not install globally:

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

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.