@agentdeploy-io/cli

CLI for building and deploying edge AI agents on AgentDeploy.

Install

npm install -g @agentdeploy-io/cli

Or use via npx without installing:

npx @agentdeploy-io/cli <command>

Quick Start

# 1. Create a new agent project
ad init --template chat-agent my-agent

# 2. Navigate and install
cd my-agent
npm install

# 3. Login to AgentDeploy
ad login --api-key ad_live_xxxxx

# 4. Run locally
ad dev

# 5. Deploy to the edge
ad deploy

Commands

ad init

Create a new agent project from a template.

ad init --template <template> <name>

If no template is given, chat-agent is used.

Templates: | Template | Description | |---|---| | chat-agent | Chat agent with streaming, tool calling, and AIChatAgent (default) | | chat-agent-with-ui | Chat agent with a bundled React UI shell (chat/dashboard/widget) | | 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

This creates:

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

The chat-agent-with-ui template also scaffolds a ui/ directory with a Vite-powered React shell. See ad generate ui below.

ad login

Authenticate with your AgentDeploy account.

ad login --api-key <key>
# or interactive:
ad login
# custom API URL (for self-hosted installs):
ad login --api-url https://custom.api.example.com --api-key <key>

Your API key is saved to ~/.agentdeploy/credentials (chmod 600). You can also set the AGENTDEPLOY_API_KEY environment variable instead, or override the platform URL with AGENTDEPLOY_API_URL.

ad logout

Remove saved credentials.

ad logout

ad dev

Run the agent locally using Wrangler.

ad dev [--port 8787] [--remote]

This wraps wrangler dev with your project's wrangler.jsonc configuration. Use --remote to run against Cloudflare's edge.

ad deploy

Bundle and deploy your agent to the AgentDeploy platform.

ad deploy [options]

Options:

• --version <semver> — Specify a version string (default: auto-generated)
• --dry-run — Bundle only, don't upload
• --skip-validation — Skip the validation step
• --verbose — Print detailed output

What it does:

1. Bundles your TypeScript project into a single ESM module using esbuild
   • cloudflare:* modules are external (provided by the runtime)
   • @agentdeploy-io/edge-sdk is bundled in
   • Target: ES2022, ESM format, minified; max size ~3MB
2. Uploads the bundle to the platform as a new template version (POST /internal/edge/versions)
3. Auto-detects your Durable Object agent classes and registers them in the agent registry
4. Validates the script for security and compatibility
5. Publishes the version to the marketplace
6. Reprovisions a previously created deployment if deploymentId is set in the project config; otherwise it prints the dashboard link to create the first deployment from the published version

Note: ad deploy publishes template versions and updates existing deployments. Creating a brand-new deployment (provisioning a live Worker from a published version) happens in the AgentDeploy dashboard or via the platform API — run ad deploy once to publish, then provision from the dashboard.

ad secrets

Manage deployment secrets.

# Set a secret
ad secrets set STRIPE_API_KEY
ad secrets set STRIPE_API_KEY "sk_live_xxx"

# List configured secrets
ad secrets list

# Show required secrets
ad secrets required

Secrets are stored securely via Cloudflare Workers Secrets API and encrypted at rest in the AgentDeploy platform.

ad generate

Scaffold new files in your project.

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

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

# Generate a UI shell (chat, widget, dashboard, or split)
ad generate ui chat
# Creates: ui/ index.html, main.tsx, vite.config.ts

Run this inside an existing AgentDeploy project (created with ad init).

ad logs

View deployment logs and status.

# One-shot status check
ad logs

# Follow live logs via wrangler tail
ad logs --follow

ad version

Print the CLI version.

ad version

ad help

Print the full help text listing every command.

Project Structure

my-agent/
├── .agentdeploy/
│   └── config.json       # AgentDeploy project config
├── src/
│   ├── server.ts          # Agent entry point
│   ├── tools.ts           # Tool definitions (optional)
│   ├── tools.<name>.ts    # Generated by `ad generate tool` (optional)
│   └── agents.<name>.ts   # Generated by `ad generate agent` (optional)
├── ui/                    # Only for chat-agent-with-ui / `ad generate ui`
│   ├── index.html
│   ├── main.tsx
│   └── vite.config.ts
├── package.json
├── tsconfig.json
├── wrangler.jsonc         # Wrangler config (for local dev)
└── .gitignore

.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": false,
      "description": "Stripe API key for payment tools"
    }
  ],
  "deploymentId": "dep_xxx",
  "templateId": 42
}

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

The chat-agent-with-ui template adds a ui object describing the shell and build output:

{
  "template": "chat-agent-with-ui",
  "ui": {
    "shell": "chat",
    "dir": "ui",
    "buildDir": "dist/ui"
  }
}

Environment Variables

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

License

MIT