ariana

Ariana CLI

The ariana CLI runs on agent machines with a token scoped to your agent's context. It has two categories of commands:

• Self commands: Manage your own environment and automations
• Orchestration commands: Spawn and control other agents

CRITICAL: Parallel Execution

When spawning multiple agents, ALWAYS run spawn commands in parallel using &:

# CORRECT - spawn 3 agents in parallel (fast)
ariana agent spawn --project $PROJECT --branch main --name "worker-1" &
ariana agent spawn --project $PROJECT --branch main --name "worker-2" &
ariana agent spawn --project $PROJECT --branch main --name "worker-3" &
wait  # wait for all background jobs to complete

# WRONG - spawning sequentially (slow, wasteful)
ariana agent spawn --project $PROJECT --branch main --name "worker-1"
ariana agent spawn --project $PROJECT --branch main --name "worker-2"
ariana agent spawn --project $PROJECT --branch main --name "worker-3"

spawn returns immediately - it does NOT wait for the agent to be ready. You can send prompts immediately - they queue and execute when the agent is ready. There is almost never a reason to use wait.

---

Self Commands

These operate on your agent's project and user context.

Environment

# Get your environment configuration
ariana env get

# Set your environment (reads JSON from stdin)
ariana env set < config.json

Automations

# List your automations
ariana automations list

# Get automation details
ariana automations get <automation-id>

# Create an automation (reads JSON from stdin)
ariana automations create < automation.json

# Update an automation
ariana automations update <automation-id> < automation.json

# Delete an automation
ariana automations delete <automation-id>

---

Orchestration Commands

These manage other agents. Agent ID is optional - if omitted, uses the last agent you interacted with or your most recently created agent.

Listing & Querying

# List agents
ariana agents list
ariana agents list --project <project-id>

# Get agent details
ariana agents get [<agent-id>]

# List projects
ariana projects list

# Get conversation history
ariana agent conversation [<agent-id>]
ariana agent conversation [<agent-id>] --limit 10

Creating Agents

Each agent runs on its own isolated machine (VPS). Choose the right command:

• spawn - Create a fresh agent from a git branch. Use this for new work.
• fork - Clone an existing agent's entire disk state (snapshot). Use this to duplicate an agent's progress. You can fork yourself (ariana agent fork $AGENT_ID) to create agents that inherit your full context, conversation history, and disk state — this is the right way to "multiply yourself" for parallel work.

# Spawn: fresh agent from git branch (most common)
ariana agent spawn --project <project-id> --branch main --name "feature-worker"
ariana agent spawn --project <project-id> --branch feature/foo --name "foo-worker"

# Fork: copy another agent's disk state (NOT git fork!)
# Use when you want to duplicate an agent's work-in-progress
ariana agent fork <source-agent-id> --name "forked-worker"

Note: Both return immediately. Prompts queue automatically - no need to wait.

Controlling Agents

# Send a task (prompts queue automatically)
ariana agent prompt [<agent-id>] "implement the login feature"
ariana agent prompt [<agent-id>] "fix the bug" --model opus

# Interrupt current work and send new task
ariana agent prompt [<agent-id>] "new urgent task" --interrupt

# Stop a running agent
ariana agent interrupt [<agent-id>]

# Rename an agent
ariana agent rename [<agent-id>] "new-name"

---

Key Behaviors

Prompt Queuing

Prompts are automatically queued. Send a prompt even if the agent is busy - it will be processed when the current task finishes. Use --interrupt to stop current work immediately.

Agent ID Auto-Selection

When you omit the agent ID, the CLI:

1. Uses the last agent you interacted with on this machine
2. Falls back to your most recently created agent

The CLI prints which agent was selected before executing.

Model Selection

Use --model opus for complex tasks, --model haiku for simple ones. Default is sonnet.

---

Agent States

• provisioning - Machine being allocated
• cloning - Repository being cloned
• ready - Ready to receive prompts
• running - Currently executing a task
• idle - Finished task, waiting for next prompt
• archived - Agent archived
• error - Something went wrong

---

Environment Configuration

Environments provide variables and files to your agent.

JSON Schema

{
  "name": "my-environment",
  "envContents": "API_KEY=xxx\nDATABASE_URL=postgres://...",
  "secretFiles": [
    {
      "path": ".config/credentials.json",
      "contents": "{\"token\": \"...\"}"
    }
  ],
  "sshKeyPair": {
    "publicKey": "ssh-ed25519 AAAA...",
    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
    "keyName": "id_ed25519"
  }
}

Fields:

• name - Environment name (unique per user+project)
• envContents - Variables in .env format (KEY=value per line)
• secretFiles - Files written to project directory (paths relative to project root)
• sshKeyPair - SSH keypair deployed to ~/.ssh/{keyName} (for git auth)

---

Automation Configuration

Automations run scripts when events occur on your agent.

JSON Schema

{
  "name": "run-tests-before-commit",
  "trigger": {
    "type": "on_before_commit"
  },
  "scriptLanguage": "bash",
  "scriptContent": "npm test",
  "blocking": true,
  "feedOutput": true
}

Fields:

• name - Automation name (unique per user+project)
• trigger - When to run (see trigger types below)
• scriptLanguage - "bash", "javascript", or "python"
• scriptContent - Your script code
• blocking - If true, agent waits for completion
• feedOutput - If true, output becomes agent context

Trigger Types

Trigger Examples

{ "type": "on_after_edit_files", "fileGlob": "*.ts" }
{ "type": "on_after_run_command", "commandRegex": "^npm " }
{ "type": "on_automation_finishes", "automationId": "automation_abc123" }

Available Variables

Scripts have access to these environment variables:

Control Functions

Scripts can control the agent:

Bash:

echo "ARIANA_CONTROL:STOP_AGENT"
echo "ARIANA_CONTROL:QUEUE_PROMPT:Review the failing tests"

JavaScript/Python:

stopAgent();
queuePrompt("Review the failing tests");

Example Automations

Pre-commit tests:

{
  "name": "pre-commit-tests",
  "trigger": { "type": "on_before_commit" },
  "scriptLanguage": "bash",
  "scriptContent": "npm test",
  "blocking": true,
  "feedOutput": true
}

Lint on edit:

{
  "name": "lint-typescript",
  "trigger": { "type": "on_after_edit_files", "fileGlob": "*.ts" },
  "scriptLanguage": "bash",
  "scriptContent": "npx eslint $INPUT_FILE_PATH --fix",
  "blocking": false,
  "feedOutput": false
}

Important Notes

• on_before_commit and on_before_push_pr must have blocking: true
• Exit code 0 = success; non-zero = failure (blocks commit/PR for "before" triggers)
• Script output limited to 1000 lines