CLI Reference

Complete command-line reference for the agentcmd CLI tool.

Installation

# Run without installing
npx agentcmd [command]

# Install globally
npm install -g agentcmd
agentcmd [command]

Global Options

Available on all commands:

Option	Description
`-V, --version`	Output the version number
`-h, --help`	Display help for command

Commands

`agentcmd install`

Initialize database and configuration for agentcmd.

Usage:

agentcmd install [options]

Options:

Option	Description	Default
`--force`	Overwrite existing database	`false`

Examples:

# First-time installation
agentcmd install

# Reinstall and reset database
agentcmd install --force

What it does:

Creates SQLite database at ~/.agentcmd/agentcmd.db
Runs Prisma migrations
Initializes configuration file at ~/.agentcmd/config.json
Sets up default workflow templates

Warning: --force flag will delete your existing database and all data. Use with caution.

`agentcmd start`

Start the agentcmd server (frontend, backend, and Inngest dev server).

Usage:

agentcmd start [options]

Options:

Option	Description	Default
`-p, --port <number>`	Backend API server port	`4100`
`--inngest-port <number>`	Inngest dev UI port	`8288`
`--host <address>`	Server host address	`127.0.0.1`

Examples:

# Start with default ports
agentcmd start

# Custom backend port
agentcmd start --port 4000

# Custom Inngest port
agentcmd start --inngest-port 9000

# Bind to all interfaces
agentcmd start --host 0.0.0.0

Services Started:

Service	Default Port	Access
AgentCmd UI & API	4100	http://localhost:4100
Inngest Dev UI	8288	http://localhost:8288

Environment Variables: The start command respects these environment variables:

PORT - Backend port (overridden by --port)
HOST - Server host (overridden by --host)
INNGEST_DEV_PORT - Inngest port (overridden by --inngest-port)
DATABASE_URL - Custom database location
LOG_LEVEL - Logging verbosity (debug, info, warn, error)

Keep the terminal open to see live logs from workflows. Open a new tab for other commands.

`agentcmd config`

Manage agentcmd configuration.

Usage:

agentcmd config [options]

Options:

Option	Description
`--show`	Display current configuration
`--edit`	Open config file in $EDITOR
`--get <key>`	Get value of specific key
`--set <key=value>`	Set value of specific key
`--path`	Print config file path

Examples:

# Display all configuration
agentcmd config --show

# Output:
```text title="Config Display"
{
  "database": {
    "url": "file:/Users/you/.agentcmd/agentcmd.db"
  },
  "server": {
    "port": 4100,
    "host": "127.0.0.1"
  },
  "inngest": {
    "devPort": 8288
  }
}

# Get specific value
agentcmd config --get server.port

# Output:
```text title="Config Value Output"
4100

# Set server port
agentcmd config --set server.port=4000

# Set multiple values
agentcmd config --set server.port=4000
agentcmd config --set server.host=0.0.0.0

# Open in default editor
agentcmd config --edit

# Set custom editor first
export EDITOR=vim
agentcmd config --edit

Config File Location:

# Print config path
agentcmd config --path

# Typical locations:
# macOS/Linux: ~/.agentcmd/config.json
# Windows: %USERPROFILE%\.agentcmd\config.json

Configuration File

Default Configuration

The default config file at ~/.agentcmd/config.json:

~/.agentcmd/config.json

{
  "database": {
    "url": "file:~/.agentcmd/agentcmd.db"
  },
  "server": {
    "port": 4100,
    "host": "127.0.0.1"
  },
  "inngest": {
    "devPort": 8288,
    "signingKey": "",
    "eventKey": ""
  },
  "ai": {
    "defaultProvider": "claude",
    "providers": {
      "claude": {
        "apiKey": ""
      },
      "openai": {
        "apiKey": ""
      },
      "gemini": {
        "apiKey": ""
      }
    }
  },
  "workflows": {
    "templatesPath": "~/.agentcmd/workflows",
    "maxConcurrent": 5
  }
}

Configuration Schema

Database Configuration (database):

Key	Type	Description	Default
`url`	string	SQLite database file path	`file:~/.agentcmd/agentcmd.db`

Server Configuration (server):

Key	Type	Description	Default
`port`	number	Backend API port	`4100`
`host`	string	Server bind address	`127.0.0.1`

Inngest Configuration (inngest):

Key	Type	Description	Default
`devPort`	number	Inngest dev UI port	`8288`
`signingKey`	string	Inngest signing key (optional)	`""`
`eventKey`	string	Inngest event key (optional)	`""`

AI Provider Configuration (ai):

Key	Type	Description	Default
`defaultProvider`	string	Default AI provider	`"claude"`
`providers.claude.apiKey`	string	Anthropic API key	`""`
`providers.openai.apiKey`	string	OpenAI API key	`""`
`providers.gemini.apiKey`	string	Google Gemini API key	`""`

Workflow Configuration (workflows):

Key	Type	Description	Default
`templatesPath`	string	Custom workflow templates directory	`~/.agentcmd/workflows`
`maxConcurrent`	number	Max concurrent workflow executions	`5`

Environment Variables

Development

Variable	Description	Default
`NODE_ENV`	Environment mode	`development`
`LOG_LEVEL`	Logging verbosity	`info`
`PORT`	Backend server port	`4100`
`HOST`	Server host address	`127.0.0.1`
`DATABASE_URL`	Database connection string	`file:~/.agentcmd/agentcmd.db`

Inngest

Variable	Description	Required
`INNGEST_DEV_PORT`	Inngest dev UI port	No
`INNGEST_SIGNING_KEY`	Inngest signing key (prod)	Production only
`INNGEST_EVENT_KEY`	Inngest event key (prod)	Production only

AI Providers

Variable	Description	Required
`ANTHROPIC_API_KEY`	Claude API key	For Claude agents
`OPENAI_API_KEY`	OpenAI API key	For GPT/Codex agents
`GOOGLE_AI_API_KEY`	Gemini API key	For Gemini agents

API keys can be set via environment variables or in the config file. Environment variables take precedence.

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Database error
`4`	Port already in use
`5`	Missing dependencies

Configuration Reference - Detailed configuration guide
Environment Variables - All env vars
Installation - Getting started guide

CLI Reference

On this page