Getting Started with the CLI

Everything you do with Agentuity goes through the CLI: creating projects, running locally, deploying to the cloud, and debugging live agents. The Web App stays synced when you need a visual interface.

Installation

Install the CLI using the universal installer:

curl -sSL https://agentuity.sh | sh

Alternatively, install via package manager: bun add -g @agentuity/cli

Verify the installation:

agentuity --version

Upgrading

Upgrade the CLI to the latest version:

agentuity upgrade

Force upgrade even if already on the latest version:

agentuity upgrade --force

The CLI periodically checks for new versions and prompts you to upgrade when one is available.

Authentication

Login to Your Account

Authenticate using a browser-based login flow:

agentuity auth login
# or simply
agentuity login

This command:

1. Generates a one-time password and opens your browser
2. Prompts you to authenticate in the web app
3. Saves your API credentials locally

Check your authentication status:

agentuity auth whoami

Get Your API Key

Display the API key for your authenticated account:

agentuity auth apikey

Create a New Account

Sign up for a new Agentuity account directly from the CLI:

agentuity auth signup

This opens your browser to complete account creation, then automatically saves your credentials locally.

Logout

Clear your local credentials:

agentuity auth logout
# or simply
agentuity logout

Preferences

Set default organization and region to avoid specifying them on every command.

Organization Preferences

# Set default organization
agentuity auth org select org_abc123
 
# Show current default organization
agentuity auth org current
 
# Clear default organization
agentuity auth org unselect

When a default organization is set, commands that support --org will use it automatically.

Region Preferences

# Set default region for deployments
agentuity cloud region select usw
 
# Show current default region
agentuity cloud region current
 
# Clear default region
agentuity cloud region unselect

Creating Projects

Create a New Project

The quickest way to get started is the interactive project creation:

agentuity project create
# or simply
agentuity create

Create a project with a specific name:

agentuity project create --name my-agent

Create a project in a specific directory:

agentuity project create --name my-agent --dir ~/projects/agents

Default Template

Running agentuity create currently scaffolds a project with:

• Translation agent: Demonstrates AI Gateway, thread state, and structured logging
• API routes: Shows agent integration and state management endpoints
• React frontend: Pre-configured with Tailwind CSS
• Workbench: Local testing UI at /workbench
• Evaluations: Example eval setup for testing agent behavior

The agent uses the OpenAI SDK routed through Agentuity's AI Gateway. This means you don't need a separate OpenAI API key: requests are authenticated with your Agentuity credentials and billed through your Agentuity account.

Project Creation Options

Example:

agentuity project create \
  --name customer-service-bot \
  --dir ~/projects \
  --no-build

Headless Project Creation

Create projects non-interactively for CI/CD pipelines and automation:

# Create with new database and storage
agentuity project create \
  --name my-agent \
  --database new \
  --storage new \
  --enable-auth
 
# Skip optional resources
agentuity project create \
  --name my-agent \
  --database skip \
  --storage skip
 
# Use existing resources
agentuity project create \
  --name my-agent \
  --database my-existing-db \
  --storage my-bucket

Managing Projects

List Projects

View all registered projects:

agentuity project list

For machine-readable output (useful for scripts and AI coding agents):

agentuity --json project list

Show Project Details

View details for a specific project:

agentuity project show <project-id>

Delete a Project

Delete projects interactively:

agentuity project delete

Delete a specific project:

agentuity project delete <project-id>

Skip confirmation prompt:

agentuity project delete <project-id> --confirm

Import a Project

Register an existing local Agentuity project with the cloud:

# Import current directory
agentuity project import
 
# Import from specific directory
agentuity project import --dir ./my-existing-project
 
# Validate without importing
agentuity project import --validate-only

The import command verifies that the directory contains a valid Agentuity project. If an agentuity.json already exists, it validates cloud access. If no agentuity.json exists, it checks for @agentuity/runtime and an agentuity.config.ts file (either in the root or in an agentuity/ subdirectory for parent-project layouts).

Command Shortcuts

Several common commands have shortcuts that let you skip the subcommand prefix:

All other commands require their full prefix (e.g., agentuity cloud session list, agentuity auth ssh add).

Global Options

The CLI supports several global flags that work with any command:

JSON Output

All commands support --json for machine-readable output, useful for shell scripts and AI coding agents:

# Get JSON output for scripting
agentuity --json auth whoami
 
# Parse with jq (a command-line JSON processor)
agentuity --json project list | jq '.[].name'

jq is a lightweight command-line JSON processor. Install via brew install jq (macOS) or apt install jq (Linux).

Log Levels

Control CLI verbosity:

# Detailed debugging output
agentuity --log-level=debug project create
 
# Only show errors
agentuity --log-level=error build

SSH Key Management

Add SSH keys to your account for secure container access during development and debugging.

List SSH Keys

View all SSH keys on your account:

agentuity auth ssh list

Add an SSH Key

Add a new SSH key interactively (automatically discovers keys in ~/.ssh/):

agentuity auth ssh add

Add a specific key file:

agentuity auth ssh add --file ~/.ssh/id_ed25519.pub

Pipe a key from stdin:

cat ~/.ssh/id_rsa.pub | agentuity auth ssh add

Remove an SSH Key

Remove keys interactively:

agentuity auth ssh delete

Remove a specific key by fingerprint:

agentuity auth ssh delete <fingerprint>

SSH keys enable secure access to deployed agent containers for debugging and log inspection. See Debugging Deployments for details.

Next Steps

Now that you have the CLI installed and authenticated:

• Local Development: Run agents locally with hot reload
• Deploying to the Cloud: Deploy agents to Agentuity Cloud
• Managing Cloud Storage: Inspect storage, env vars, and secrets
• OpenCode Plugin: AI-assisted development with specialized agents