agentpilot

CLI for AgentPilot — one-click IDE hook setup for AI agent monitoring.

Quick Start

npx agentpilot init

This will:

1. Authenticate with your API key
2. Auto-detect your IDE (Claude Code, Cursor, or Windsurf)
3. Create an agent on your dashboard
4. Install hook scripts with safe settings merge
5. Verify the connection

Commands

init

Interactive setup wizard. Auto-detects IDE, creates agent, installs hooks.

npx agentpilot init                                            # interactive
npx agentpilot init --key ap_xxx --type claude-code --name "X" # non-interactive
npx agentpilot init --key ap_xxx --type cursor --yes           # skip confirmations

status

List your agents and their current status.

npx agentpilot status

login

Store your API key for future use.

npx agentpilot login --key ap_xxx

Flags

| Flag | Description | |------|-------------| | --key ap_xxx | API key (or set via stored config) | | --type <type> | IDE type: claude-code, cursor, windsurf | | --name <name> | Agent name (defaults to directory name) | | --yes | Skip confirmation prompts | | --base-url <url> | Custom API base URL | | --version | Show version | | --help | Show help |

Environment Variables

| Variable | Description | |----------|-------------| | AGENTPILOT_BASE_URL | Override API base URL (for self-hosted/staging) |

Credentials

API keys are stored in ~/.agentpilot/config.json with mode 0600 on Unix. On Windows, the file is protected by the user's home directory ACLs.

Get your API key at app.agentpilot.dev/settings/integrations.

Settings Merge

The CLI safely merges hooks into your IDE config:

• Creates a timestamped backup before any change
• Only touches the hooks section, preserving all other settings
• Idempotent: running twice is a no-op
• Shows a diff before applying (skip with --yes)

Backup Files

Backup files (*.bak.<timestamp>) are kept in the same directory. Only the 3 most recent backups per file are retained. Add *.bak.* to your .gitignore.

Development

Building

cd packages/cli
npm run build        # compile TypeScript → dist/

Testing

npm test             # run tests once (vitest)
npm run test:watch   # watch mode

Publishing to npm

The package name is agentpilot (unscoped). Before publishing for the first time:

1. Log in to npm: npm login (or npm whoami to verify)
2. Preview the package: npm pack --dry-run
3. Publish: npm publish from packages/cli/

The prepublishOnly script automatically runs build + tests before every publish.

After publishing, verify: npx agentpilot --version

Note: If the unscoped name agentpilot is unavailable on npm, switch to a scoped name (e.g. @agentpilot/cli) in package.json and publish with npm publish --access public. Update all npx agentpilot references in the codebase accordingly.

Requirements

• Node.js 18+
• bash (Git Bash on Windows, native on macOS/Linux)
• curl (included in Git Bash, native on macOS/Linux)