@capsuleer/cli

The Capsuleer command-line interface. Install and manage modules, publish to the registry, search for capabilities, and interact with a live capsule environment from the terminal.

bunx @capsuleer/cli
# or after global install:
capsuleer

Commands

Environment

# Install the capsule environment to ~/.capsuleer/environment/
capsuleer env:install

# Remove the environment
capsuleer env:uninstall

# Regenerate the module manifest cache
capsuleer prepare

Modules

# Search the registry
capsuleer search
capsuleer search github

# Install a module
capsuleer install github
capsuleer install linear

# List installed modules
capsuleer list
capsuleer list --outdated    # show which have newer versions

# Upgrade modules
capsuleer upgrade            # upgrade all
capsuleer upgrade github     # upgrade one

# Remove a module
capsuleer remove github

Publishing

# Publish a module to npm + register in the Capsuleer registry
capsuleer publish
capsuleer publish ./path/to/my-module

# Re-register an already-published npm package (no version bump, no npm publish)
capsuleer publish --registry-only

# Publish with npm OTP (if not using an automation token)
capsuleer publish --otp=123456

Publishing:

1. Extracts a type manifest from index.ts via the TypeScript compiler API
2. Writes capsuleer.manifest.json into the package (shipped with npm)
3. Bumps the patch version in package.json
4. Runs npm publish --access public
5. Registers the module in the Capsuleer registry with the manifest and README

Config

# Set your registry secret (required to publish)
capsuleer config set registry_secret <your-secret>

# View a config value
capsuleer config get registry_secret

# Remove a value
capsuleer config unset registry_secret

Registry secrets are available at axon.arclabs.it/settings.

REPL

# Open an interactive TypeScript REPL inside a live capsule
capsuleer repl

The REPL boots a capsule with the full module stack loaded. Every line is executed as TypeScript with all registered globals in scope — useful for testing module behaviour before using them in an agent.

capsuleer> const files = await fs.find("**/*.ts", { cwd: "/project" })
capsuleer> files.length
42
capsuleer> await $`git status`

Writing a module

A publishable module is a standard npm package:

my-module/
├── package.json     # name must be "@capsuleer/<id>"
├── index.ts         # default export from defineModule()
└── README.md        # shown in registry — write it

// index.ts
import { defineModule } from "@capsuleer/core"

const myTool = {
  /**
   * Do something useful.
   * @param input - The thing to process
   */
  async process(input: string): Promise<{ result: string }> {
    // ...
    return { result: "done" }
  }
}

export default defineModule({
  name: "my-tool",
  version: "1.0.0",
  description: "Does something useful",
  api: myTool,
})

// package.json
{
  "name": "@capsuleer/my-tool",
  "version": "1.0.0",
  "type": "module",
  "main": "./index.ts"
}

Then publish:

cd my-module
capsuleer publish

The CLI handles versioning, manifest generation, npm publishing, and registry registration in one step.

How publishing works

The publish command uses the TypeScript compiler API to statically analyse index.ts and extract the full type signature of every function in the api object — including JSDoc comments, parameter names, types, and return types. This generates a capsuleer.manifest.json that ships alongside the source and is stored in the registry.

When the module is installed, the manifest is cached in ~/.capsuleer/installed.json. On capsule boot, the environment emits a module:manifest event for every loaded module — built-in and installed — so the LLM always has accurate TypeScript declarations and can't hallucinate an API that isn't registered.