@soleri/cli

Developer CLI for creating and managing Soleri AI agents.

Part of the Soleri framework — building AI assistants that learn, remember, and grow with you.

Quick Start

npx @soleri/cli create my-agent

The interactive wizard walks you through agent configuration: name, role, domains, principles, and greeting. When you're done, it scaffolds a complete agent project ready to build and run.

Commands

| Command | Description | | ---------------------------------- | ------------------------------------------------------- | | soleri create [name] | Interactive wizard to scaffold a new agent | | soleri list [dir] | Show agents in a directory | | soleri add-domain <domain> | Add a knowledge domain to the agent in cwd | | soleri install-knowledge <pack> | Install knowledge packs from a local path | | soleri dev | Run agent in development mode (stdio MCP server) | | soleri doctor | Health check — Node, npm, tsx, agent, deps, build, MCP | | soleri hooks add <editor> | Generate editor hooks/config files | | soleri hooks remove <editor> | Remove editor hooks/config files | | soleri hooks list | Show installed editor hooks | | soleri hooks add-pack <pack> | Install a hook pack globally (~/.claude/) | | soleri hooks remove-pack <pack> | Remove a hook pack | | soleri hooks list-packs | Show available hook packs and their status | | soleri hooks upgrade-pack <pack> | Upgrade a hook pack to the latest version | | soleri uninstall [dir] | Remove agent MCP entries (or all artifacts with --full) |

Create

# Interactive wizard
soleri create my-agent

# Force host setup target
soleri create my-agent --setup-target codex

# Non-interactive with config file
soleri create --config agent.json

The config file follows the same schema as the wizard output:

{
  "id": "my-agent",
  "name": "My Agent",
  "role": "Code Review Advisor",
  "description": "Reviews code for quality and security issues.",
  "domains": ["security", "code-quality"],
  "principles": ["Security is not optional"],
  "greeting": "Ready to review.",
  "outputDir": ".",
  "setupTarget": "both",
  "hookPacks": ["typescript-safety", "clean-commits"]
}

Hook Packs

Hook packs are curated sets of quality gate rules that install as hookify files to ~/.claude/. They enforce code standards during AI-assisted development.

Built-in packs:

| Pack | Hooks | Description | | ------------------- | ---------------------------------------------------- | ------------------------- | | typescript-safety | no-any-types, no-console-log | Block unsafe TS patterns | | a11y | semantic-html, focus-ring-required, ux-touch-targets | Accessibility enforcement | | css-discipline | no-important, no-inline-styles | CSS best practices | | clean-commits | no-ai-attribution | No AI attribution in git | | full | All 8 hooks | Complete quality suite |

soleri hooks list-packs                    # See available packs
soleri hooks add-pack typescript-safety    # Install globally
soleri hooks add-pack full --project       # Install to project .claude/
soleri hooks upgrade-pack full             # Upgrade to latest version
soleri hooks remove-pack typescript-safety # Remove

Custom packs: Create a .soleri/hook-packs/<pack-name>/ directory with a manifest.json and hookify .md files. Local packs override built-in packs with the same name.

Editor Hooks

Generate editor-specific configuration files for your agent:

soleri hooks add claude-code   # .claude/settings.json with lifecycle hooks
soleri hooks add cursor        # .cursorrules
soleri hooks add windsurf      # .windsurfrules
soleri hooks add copilot       # .github/copilot-instructions.md

Development Workflow

soleri create my-agent         # Scaffold
cd my-agent
npm install                    # Install dependencies
npm run build                  # Build
soleri dev                     # Run locally
soleri doctor                  # Verify everything works
soleri hooks add claude-code   # Add editor hooks
soleri add-domain security     # Add a domain later

Uninstall

Remove an agent's MCP server registration:

soleri uninstall [dir]                    # Remove MCP server entries only
soleri uninstall [dir] --target claude    # Remove from Claude only

Fully remove an agent and all its artifacts:

soleri uninstall [dir] --full             # Interactive confirmation
soleri uninstall [dir] --full --dry-run   # Preview what would be removed
soleri uninstall [dir] --full --force     # Skip confirmation (CI/scripting)

Artifacts removed with --full

| Artifact | Location | | ------------------ | ---------------------------------------------------------------------------- | | MCP server entries | ~/.claude.json, ~/.codex/config.toml, ~/.config/opencode/opencode.json | | Project directory | ~/projects/<agent>/ or specified dir | | Data directory | ~/.soleri/<agent>/ (current), ~/.<agent>/ (legacy) | | CLAUDE.md blocks | ~/CLAUDE.md, ~/.claude/CLAUDE.md | | Permission entries | ~/.claude/settings.local.json | | Launcher script | /usr/local/bin/<agent> |

How It Works

The CLI wraps @soleri/forge — the same scaffolding engine that powers AI-driven agent creation via MCP. The CLI provides a terminal-first interface for the same operations.

Development

# From monorepo root
npm install
npm run build --workspace=@soleri/cli
npm run test --workspace=@soleri/cli

Requirements

• Node.js 18+
• npm 8+

License

Apache-2.0