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 App stays synced when you need a visual interface.

Installation

Install the CLI using the universal installer:

curl -sSL https://v1.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

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

• --name <name>: Project name
• --dir <path>: Directory to create the project in
• --template <name>: Template to use (optional, defaults to "default")
• --no-install: Skip dependency installation
• --no-build: Skip initial build
• --no-register: Don't register the project with Agentuity Cloud

Example:

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

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

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

Configuration Profiles

The CLI supports multiple configuration profiles for different environments (development, staging, production).

Switch Profiles

Switch to a different profile:

agentuity profile use production

List Profiles

View available profiles:

agentuity profile list

Configuration is stored in ~/.config/agentuity/production.yaml by default. Override with --config=/path/to/config.yaml.

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 Data: Inspect storage, env vars, and secrets