Skip to Content
Developer DocsCLI Quick StartUsing the CLI

CLI Command Reference

Complete guide to all AgentPress CLI commands for creating, managing, and maintaining your projects.

Installation

Run the latest version with bunx (no installation required):

bunx @agentpress/cli@latest <command>

Commands

create

Create a new AgentPress project from the official template.

bunx @agentpress/cli@latest create <project-name> [options]

Arguments:

  • <project-name> - Name for your new project directory

Options:

  • --template <url> - Use a custom template repository (default: official AgentPress template)
  • --version <tag> - Clone a specific template version/tag
  • --verbose - Enable detailed logging

Interactive Prompts:

  1. GitHub Personal Access Token - For cloning the template (requires repo scope)

    ⚠️ Beta Access: Contact the AgentPress team for repository access before generating your token.

  2. npm Access Token - For installing private packages

    ⚠️ Beta Access: Request an npm token from the AgentPress team.

  3. Run setup wizard? - Configure now or later

What it does:

  1. Validates tokens and clones the template
  2. Installs dependencies
  3. Optionally runs setup wizard (database, admin account, API keys, environment)

Examples:

# Create with default template
bunx @agentpress/cli@latest create my-app
 
# Create with custom template
bunx @agentpress/cli@latest create my-app --template https://github.com/your-org/custom-template.git
 
# Create with specific version
bunx @agentpress/cli@latest create my-app --version v1.2.3
 
# Create with verbose logging
bunx @agentpress/cli@latest create my-app --verbose

setup

Run the interactive setup wizard to configure an existing AgentPress project.

bunx @agentpress/cli@latest setup

Prerequisites:

  • Must be run from an AgentPress project root directory
  • PostgreSQL database accessible

Configuration Steps:

  1. Database - Connection details (host, port, name, credentials), creates database if needed
  2. Admin Password - For admin@agent.press (8+ chars, uppercase, lowercase, number)
  3. API Keys (optional) - OpenAI, Anthropic, Google, xAI, Ultravox
  4. Environment Files - Generates .env files with all configuration
  5. Migrations - Sets up database schema

What it generates:

my-app/
├── apps/
│   ├── api/
│   │   └── .env          # Generated with database and API configs
│   └── console/
│       └── .env          # Generated with API endpoint config

sync

Synchronize your project with the latest AgentPress template updates.

bunx @agentpress/cli@latest sync [options]

Options:

  • --verbose - Show detailed sync information

Prerequisites:

  • Must be run from an AgentPress project root directory

What it does:

  1. Validates project structure
  2. Compares package versions with template
  3. Syncs new database migrations
  4. Updates dependencies in package.json
  5. Generates sync report

Sync Process:

# 1. Sync your project
bunx @agentpress/cli@latest sync
 
# 2. Install updated dependencies
bun install
 
# 3. Run new migrations (if any)
cd apps/api && bun run db:migrate
 
# 4. Restart your development servers
bun dev

What gets synced:

  • Package versions in package.json files
  • Database migration files in apps/api/src/db/migrations
  • Dependencies and devDependencies

What is NOT synced:

  • Your custom code and agents
  • Environment variables (.env files)
  • Database data
  • Custom configuration

reset-password

Reset the admin account password.

bunx @agentpress/cli@latest reset-password

Prerequisites:

  • Must be run from an AgentPress project root directory
  • Database must be configured and accessible

Resets the password for admin@agent.press with the same validation as the setup wizard.

Workflow Examples

Starting a New Project

bunx @agentpress/cli@latest create my-app
cd my-app
bun install
bun build
bun dev
 
# Console: http://localhost:3000
# API: http://localhost:3001

Setting Up Later

bunx @agentpress/cli@latest create my-app  # Decline setup wizard
cd my-app
bunx @agentpress/cli@latest setup

Keeping Project Updated

bunx @agentpress/cli@latest sync --verbose
bun install
cd apps/api && bun run db:migrate
bun dev

Project Structure Requirements

The CLI validates your project structure by checking for:

Required Files:

  • package.json - Root monorepo configuration with AgentPress dependencies
  • apps/api/package.json - Backend application package
  • apps/console/package.json - Frontend application package

Required Directories:

  • apps/ - Contains application packages (api, console)
  • packages/ - Contains shared packages (@repo/*)

AgentPress Markers:

  • Dependencies with @agentpress/* or @repo/* namespaces
  • Proper workspace configuration

Environment Requirements

  • Node.js 22 or higher
  • Bun package manager (latest version recommended)
  • Git for template cloning and version control
  • PostgreSQL 13 or higher (with pgvector support)

Recommended Setup:

# Install Bun (if not installed)
curl -fsSL https://bun.sh/install | bash
 
# Verify installations
node --version    # Should be 22+
bun --version     # Latest recommended
psql --version    # 13+

Troubleshooting

Command Not Found

Use bunx @agentpress/cli@latest <command> or install globally with bun add -g @agentpress/cli

Project Not Recognized

Run from project root. Verify apps/ and packages/ directories exist and package.json contains @agentpress/* dependencies.

Sync Failures

Run bunx @agentpress/cli@latest sync --verbose. Ensure clean git state with git status.

Database Connection Issues

Check PostgreSQL is running (pg_isready), credentials are correct, and port 5432 isn’t blocked.

# Start PostgreSQL
brew services start postgresql  # macOS
sudo systemctl start postgresql  # Linux
 
# Or use Docker
docker run --name agentpress-db -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

Token Authentication Failures

Verify token permissions (GitHub: repo, npm: Read), hasn’t expired, and no extra spaces when pasting.

Advanced Usage

Custom Templates:

bunx @agentpress/cli@latest create my-app --template https://github.com/your-org/template.git

Version Pinning:

bunx @agentpress/cli@latest create my-app --version v1.0.0

CI/CD: Decline the setup wizard and configure via environment variables or scripts.

Getting Help

bunx @agentpress/cli@latest --help           # All commands
bunx @agentpress/cli@latest create --help    # Specific command
bunx @agentpress/cli@latest --version        # CLI version
Last updated on
Getting Started with AgentPressOverview