@402md/cli

CLI to install and manage 402.md skills across 30+ AI agents.

Quick start

# Initialize per-project config
npx @402md/cli init --mode wallet-pay --api-key sk_xxx --wallet 0xabc

# Install a skill
npx @402md/cli add ditto

# Search the marketplace
npx @402md/cli search "sentiment analysis"

Global install

npm i -g @402md/cli
402md add <skill>

Project Setup

Run init to create a .402md/ directory in your project:

npx @402md/cli init --mode wallet-pay --api-key sk_xxx --wallet 0xabc --network base-sepolia

For x402 mode (self-custody):

npx @402md/cli init --mode x402 --key 0xYOUR_PRIVATE_KEY --network base

This creates:

.402md/
├── config.json       # project config (network, agents, budget)
├── .secrets.json     # secrets (apiKey, walletPrivateKey, walletAddress) — auto-gitignored
├── installed.json    # installed skills manifest
└── skills/           # per-skill SKILL.md files

Secrets (apiKey, walletPrivateKey, walletAddress) are stored in .402md/.secrets.json with restricted file permissions (0600). The CLI automatically adds .402md/.secrets.json to your .gitignore.

The CLI walks up from the current directory to find .402md/. Falls back to ~/.402md/ if not found.

Agent Setup

On first add, an interactive selector lets you choose which agents to install to.

To configure your wallet and MCP server:

npx @402md/cli setup --key 0xabc123... --network base

The CLI automatically configures:

• Skills across all selected agents
• MCP server on supported agents (e.g. Claude Code)

Supported agents

Universal (.agents/skills) — always included: Amp, Cline, Codex, Cursor, Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode

Additional (selectable during setup): Antigravity, Augment, Claude Code, OpenClaw, CodeBuddy, Command Code, Continue, Cortex Code, Crush, Droid, Goose, Junie, iFlow CLI, Kilo Code, Kiro CLI, Kode, MCPJam, Mistral Vibe, Mux, OpenHands, Pi, Qoder, Qwen Code, Roo Code, Trae, Windsurf, Zencoder, Neovate, Pochi, AdaL

Commands

| Command | Description | |---------|-------------| | init | Initialize .402md/ in the current project | | add <skill> | Install a skill from the marketplace | | remove <name> | Remove a skill | | list | List locally installed skills | | search <query> | Search the marketplace | | setup --key <0x...> | Select agents + configure wallet and MCP server | | update [name] | Update installed skill(s) |

Examples

npx @402md/cli init --mode wallet-pay --api-key sk_xxx --wallet 0xabc
npx @402md/cli search sentiment
npx @402md/cli add sentiment-analysis
npx @402md/cli list
npx @402md/cli remove sentiment-analysis
npx @402md/cli update

Library Usage

The CLI also exports its modules for programmatic use:

import { loadConfig, createPaymentClient, searchSkills } from '@402md/cli'

const config = loadConfig()
const client = createPaymentClient(config)

const result = await client.callSkill('ditto', '/test', {
  body: { message: 'hello' }
})

See @402md/agent-tools for the recommended high-level integration.

Secrets Management

Since v0.2.0, secrets are stored separately from project config:

• .402md/config.json — safe to commit (network, agents, budget, apiBaseUrl)
• .402md/.secrets.json — contains apiKey, walletPrivateKey, walletAddress (auto-gitignored)

When you run init or setup, the CLI:

1. Writes secrets to .402md/.secrets.json with 0600 permissions
2. Adds .402md/.secrets.json to .gitignore

loadConfig() merges both files transparently, so existing code doesn't need changes.

If you have an older .402md/config.json with secrets inside, they'll migrate to .secrets.json automatically on the next init or saveConfig() call.

Payment Modes

| Mode | Config fields | Description | |------|---------------|-------------| | x402 | walletPrivateKey | Signs USDC transfers on-chain directly | | wallet-pay | apiKey + walletAddress | Backend pays on your behalf (gasless) |

Custom API URL

For local development:

npx @402md/cli init --api-url http://localhost:3001 --network base-sepolia

Or edit .402md/config.json:

{
  "apiBaseUrl": "http://localhost:3001",
  "network": "base-sepolia"
}

License

MIT