Getting Started with the CLI

The v1 CLI is designed to be your primary interface for building and managing Agentuity projects. You can create agents, inspect sessions, manage storage, debug deployments, and deploy — all without leaving your terminal. The Console stays fully synced for when you prefer a visual interface.

Installation

Install the CLI using the universal installer:

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

Verify the installation:

agentuity --version

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

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

Available Templates

agentuity project create --template openai

Project Creation Options

• --name <name>: Project name
• --dir <path>: Directory to create the project in
• --template <name>: Template to use (default: "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'

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

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>

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