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 (@agentpress/*)

AgentPress Markers:

• Dependencies with @agentpress/* 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