@karpdo/cli

Deploy and manage AI agents from your terminal — powered by karpdo.com

npm install -g @karpdo/cli

Python SDK

Prefer Python over the terminal?

pip install karpdo

import karpdo

agent = karpdo.create("My Bot").deploy()
print(agent.chat("Hello!"))

Full docs: packages/python-sdk/README.md

Quick start

# 1. Install
npm install -g @karpdo/cli

# 2. Authenticate
karp login

# 3. Deploy your first agent
karp agents deploy --name my-agent

# 4. Drop into an interactive shell on your agent
karp shell my-agent

# 5. Or chat with it
karp agents chat <agent-id>

Authentication

Run karp login to open a browser window and authorize the CLI:

karp login
# Opening browser to authenticate...
# If the browser does not open automatically, visit:
#   https://karpdo.com/cli/login?state=<state>
#
# ✓ Logged in as [email protected]

Your session token is stored locally at ~/.karp/config.json and reused for all subsequent commands.

CI / non-interactive environments:

export KARP_API_KEY=karp_sk_...
karp agents list

Get a long-lived key from karpdo.com → Dashboard → API Keys.

Commands

karp shell

Drop into a full interactive shell on a running agent — with a real PTY, just like ssh.

karp shell <name-or-id>

• Accepts the agent name (fuzzy match) or UUID
• If the agent is stopped, prompts you to start it first
• Allocates a real pseudo-terminal on the agent — interactive TUI programs (hermes, vi, htop) work correctly
• Terminal resize is forwarded automatically
• Press Ctrl+D or type exit to disconnect

$ karp shell "Kin Hing"
✓ Connected to Kin Hing — press Ctrl+D to disconnect

root@agent:~# hermes
# full interactive TUI launches here
root@agent:~# exit

karp agents

Manage your deployed agents.

# List all agents
karp agents list

# Deploy a new agent
karp agents deploy --name <name>

# Deploy with a config file
karp agents deploy --name <name> --config ./agent.json

# Check agent status
karp agents status <agent-id>

# Wait until agent reaches running or error state
karp agents status <agent-id> --wait

# Start a stopped agent
karp agents start <agent-id>

# Stop a running agent
karp agents stop <agent-id>

# Execute a single command on an agent
karp agents exec <agent-id> "uname -a"

# Chat interactively with an agent
karp agents chat <agent-id>

# View agent logs (last 100 lines)
karp agents logs <agent-id>

# Stream live logs
karp agents logs <agent-id> --follow

# Tail a specific number of lines
karp agents logs <agent-id> --lines <n>

# Delete an agent (prompts for confirmation)
karp agents delete <agent-id>

# Delete without confirmation prompt
karp agents delete <agent-id> --yes

karp keys

Manage API keys for your agents (used by external integrations).

# Create an API key for an agent
karp keys create <agent-id>

# Create with a custom name
karp keys create <agent-id> --name "production key"

# List all API keys for an agent
karp keys list <agent-id>

# Revoke an API key (prompts for confirmation)
karp keys revoke <agent-id> <key-id>

# Revoke without confirmation prompt
karp keys revoke <agent-id> <key-id> --yes

Keys are shown once on creation. Store them securely — they cannot be retrieved again.

Agent config file

Pass a JSON config to agents deploy to set tools, model, and channel integrations:

{
  "model": "claude-3-5-sonnet-20241022",
  "soul_md": "You are a helpful assistant.",
  "tools": ["web_search", "terminal"],
  "channels": [
    {
      "type": "telegram",
      "enabled": true,
      "token": "your-telegram-bot-token"
    }
  ]
}

karp agents deploy --name my-agent --config ./agent.json

Configuration

| Source | Key | Description | |---|---|---| | Environment | KARP_API_KEY | Overrides stored key | | Environment | KARP_API_URL | Override API endpoint (self-hosted) | | File | ~/.karp/config.json | Set by karp login |

Links

• Dashboard
• Documentation
• Sign up

License

MIT