CLI Guide

Complete reference for the @agentdeploy/cli — the command-line tool for building, testing, and deploying edge agents.

Installation

npm install -g @agentdeploy/cli

Or use via npx without installing:

npx @agentdeploy/cli <command>

Commands

ad init

Create a new agent project from a template.

ad init --template <template> <project-name>

Templates:

Template	Description
chat-agent	Chat agent with streaming, tool calling, and message persistence (default)
scheduled-agent	Scheduled agent with cron tasks, SQLite storage, HTTP endpoints
blank	Minimal starter with just the basics

Example:

ad init --template chat-agent my-support-bot
cd my-support-bot
npm install

Creates:

my-support-bot/
├── .agentdeploy/config.json
├── src/server.ts
├── src/tools.ts
├── package.json
├── tsconfig.json
├── wrangler.jsonc
└── README.md

ad login

Authenticate with your AgentDeploy account.

# With API key
ad login --api-key ad_live_xxxxxxxxxx

# Interactive (prompts for key)
ad login

# Custom API URL (for self-hosted)
ad login --api-url https://custom.api.com --api-key xxx

Your API key is stored in ~/.agentdeploy/credentials (chmod 600). You can also set AGENTDEPLOY_API_KEY environment variable instead.

Get your API key from Dashboard > Settings > API Keys.

ad logout

Remove saved credentials.

ad logout

ad dev

Run the agent locally. Wraps wrangler dev.

# Default (local)
ad dev

# Custom port
ad dev --port 3000

# Run against Cloudflare's remote edge
ad dev --remote

Your agent runs at http://localhost:8787. Endpoints available:

• GET /health — Health check
• GET /info — Agent metadata
• ws://localhost:8787/agents/{name}/{instance} — WebSocket for chat

ad deploy

Bundle and deploy your agent to the AgentDeploy platform.

# Deploy with auto-generated version
ad deploy

# Specify version
ad deploy --version 1.0.0

# Dry run (bundle only, don't upload)
ad deploy --dry-run

# Skip validation
ad deploy --skip-validation

# Verbose output
ad deploy --verbose

What deploy does:

1. Bundle — Runs esbuild on your TypeScript entry point, producing a single ESM module
2. Upload — POSTs the bundle to /internal/edge/versions on the platform
3. Validate — Platform runs security validation on the bundled code
4. Publish — Version is marked as published on the marketplace
5. Provision — If deploymentId exists in config, reprovisions; otherwise creates new

Bundle output:

• cloudflare:workers and cloudflare:sockets are external (provided by runtime)
• node: imports are resolved to polyfills by esbuild
• @agentdeploy/edge-sdk is bundled into the output
• Target: ES2022, ESM format, minified
• Max size: 3MB

ad secrets

Manage deployment secrets.

# Set a secret (prompts for value)
ad secrets set STRIPE_API_KEY

# Set with inline value
ad secrets set STRIPE_API_KEY "sk_live_xxx"

# List configured secrets (shows which are set/unset)
ad secrets list

# Show required secrets from manifest
ad secrets required

Secrets are stored via the platform's secret management API and bound to the Cloudflare Worker via Cloudflare Secrets API.

ad generate

Scaffold new files in your project.

# Generate a new tool file
ad generate tool inventory-check
# Creates: src/tools.inventory_check.ts

# Generate a new agent (for multi-agent projects)
ad generate agent billing
# Creates: src/agents.billing.ts

ad logs

View deployment logs and status.

# One-shot status check
ad logs

# Follow live logs (wraps wrangler tail)
ad logs --follow

ad version

Show CLI version.

ad version

Environment variables

Variable	Description	Default
AGENTDEPLOY_API_KEY	Override login credentials	(from ad login)
AGENTDEPLOY_API_URL	Override API URL	https://api.agentdeploy.io

Project config

.agentdeploy/config.json:

{
  "projectId": "my-agent",
  "name": "My Agent",
  "template": "chat-agent",
  "entrypoint": "src/server.ts",
  "model": "openai/gpt-4o-mini",
  "secrets": [
    { "key": "STRIPE_API_KEY", "required": true, "description": "Stripe key" }
  ],
  "deploymentId": "dep_xxx",
  "templateId": 42
}

Field	Description
projectId	Project identifier (used in worker naming)
name	Display name
template	Template type (chat-agent, scheduled-agent, blank)
entrypoint	Path to main TypeScript file (relative to project root)
model	Model hint (platform may override)
secrets	Secret manifest entries
deploymentId	Set after first deploy (enables reprovisioning)
templateId	Set after first publish to marketplace

Global credentials

~/.agentdeploy/credentials:

{
  "apiKey": "ad_live_xxxxx",
  "apiUrl": "https://api.agentdeploy.io",
  "userId": "user-uuid"
}

File permissions are set to 600 (owner read/write only).

Common workflows

First deploy

ad init --template chat-agent my-agent
cd my-agent
npm install
ad login --api-key ad_live_xxx
ad dev                    # Test locally
ad deploy                 # Deploy to platform

Update an existing agent

# Make code changes...
ad deploy --version 1.1.0

Add secrets to a deployment

ad secrets set STRIPE_API_KEY
ad secrets set DATABASE_URL "postgres://..."
ad secrets list

Add a new tool

ad generate tool check-inventory
# Edit src/tools.check_inventory.ts with your logic
# Import and use in src/server.ts