agentpane-cli

name	agentpane-cli
description	Manage AgentPane codespaces, tasks, agents, sessions, and worktrees from the CLI. Use when the user needs to list/create/manage tasks, start/stop agents, view session events, check git status, or interact with the AgentPane API programmatically.

AgentPane CLI

The AgentPane CLI (agentpane) is a Go-based command-line tool for managing codespaces, tasks, agents, sessions, and worktrees through the AgentPane API. It provides full programmatic access to the AgentPane platform for automation, scripting, and interactive use.

Quick Start

Build

cd cli
make build

This produces the agentpane binary in the cli/ directory.

Verify

./agentpane health

Expected output: AgentPane API is healthy or JSON health response with -json.

Minimal Setup

export AP_API_TOKEN="ap_your_token"
export AP_ADDRESS="http://localhost:3001"
./agentpane health

Configuration

Environment Variables

Variable	Description	Default
AP_API_TOKEN	API authentication token	(required)
AP_ADDRESS	AgentPane API base URL	http://localhost:3001
AP_CODESPACE	Default codespace ID or name (avoids -codespace on every command)	(none)

Global Flags

These flags override the corresponding environment variables:

Flag	Description
-token <string>	API token (overrides AP_API_TOKEN)
-address <string>	API base URL (overrides AP_ADDRESS)
-codespace <string>	Codespace ID or name (overrides AP_CODESPACE)
-json	Output in JSON format instead of human-readable tables

Precedence

Flags take precedence over environment variables. For example:

# Uses AP_ADDRESS from env, but overrides token
AP_ADDRESS="http://localhost:3001" ./agentpane -token "ap_override" health

Commands

Health Check

Verify the AgentPane API is reachable and healthy.

agentpane health

agentpane health -json

Codespace Management

Codespaces are the top-level organizational unit (formerly called "projects"). Each codespace maps to a git repository.

List all codespaces

agentpane codespace list

agentpane codespace list -json

Show codespace details

agentpane codespace show <codespace-id>

agentpane codespace show <codespace-id> -json

Create a codespace

agentpane codespace create -name "My Project" -path "/path/to/repo" -project-id <project-id>

Task Management

Tasks represent units of work that agents execute. Tasks move through columns on a Kanban board.

Task columns (lifecycle)

Column	Description
backlog	Not yet scheduled
queued	Ready to be picked up
in_progress	Agent is actively working
waiting_approval	Agent completed, awaiting human review
verified	Work approved and complete

Task priorities

Priority	Description
high	Urgent work
medium	Normal priority
low	Can wait

List tasks

agentpane task list -codespace <name-or-id>

With the AP_CODESPACE env var set:

agentpane task list

Create a task

agentpane task create -codespace <name-or-id> -title "Fix login bug" -priority high

With a skill assigned (skill ID is the directory name under .Codex/skills/):

agentpane task create -codespace <name-or-id> -title "Deploy infrastructure" -skill terraform-stacks -skill-name "Terraform Stacks"

agentpane task create -codespace <name-or-id> -title "Refactor auth module" -priority medium

With auto-start (creates and immediately starts the agent):

agentpane task create -codespace <name-or-id> -title "Build VPC module" -skill tf-module-e2e -auto-start

With agent approval (plans are auto-reviewed instead of waiting for human):

agentpane task create -codespace <name-or-id> -title "Build S3 module" -skill tf-module-e2e -auto-start -approval-mode agent

Show task details

agentpane task show <task-id>

agentpane task show <task-id> -json

Move a task to a different column

agentpane task move <task-id> in_progress

agentpane task move <task-id> queued

Run a task (shortcut)

This is a convenience command that moves a task to in_progress, which automatically triggers agent assignment and execution.

agentpane task run <task-id>

This is equivalent to agentpane task move <task-id> in_progress.

Approve a task plan

When an agent completes planning and the task is in waiting_approval, approve the plan to proceed to execution:

agentpane task approve <task-id>

Reject a task plan

Reject a plan with a reason, sending the agent back to revise:

agentpane task reject <task-id> -reason "needs more detail on error handling"

Agent Management

Agents are Codex-powered workers that execute tasks. Each agent runs in its own git worktree for isolation.

Agent statuses

Status	Description
idle	Not currently working
starting	Being initialized
planning	Exploring codebase and creating a plan
running	Executing the approved plan
paused	Temporarily stopped
error	Encountered an error
completed	Finished work

List agents

agentpane agent list -codespace <name-or-id>

Start an agent on a task

agentpane agent start <agent-id> -task <task-id>

Stop an agent

agentpane agent stop <agent-id>

Session Management

Sessions track the event stream for an agent's execution. Each agent run creates a session with real-time events.

List sessions

agentpane session list -codespace <name-or-id>

Filter by status:

agentpane session list -codespace <name-or-id> -status active

Show session details

agentpane session show <session-id>

View session events

View the event stream for a session (agent turns, tool calls, outputs):

agentpane session events <session-id>

Limit the number of events:

agentpane session events <session-id> -limit 50

With JSON output for parsing:

agentpane session events <session-id> -limit 100 -json

Worktree Management

Worktrees are isolated git working directories created for each agent. They allow agents to make changes without affecting the main branch.

List worktrees

agentpane worktree list -codespace <name-or-id>

View worktree diff

See what changes an agent made in its worktree:

agentpane worktree diff <worktree-id>

Merge a worktree

Merge the agent's changes back to the target branch:

agentpane worktree merge <worktree-id>

Merge and delete the worktree after:

agentpane worktree merge <worktree-id> -delete

Specify a target branch:

agentpane worktree merge <worktree-id> -delete -target-branch main

Git Operations

Convenience commands for checking git status of codespaces.

Repository status

agentpane git status -codespace <name-or-id>

List branches

agentpane git branches -codespace <name-or-id>

Common Workflows

1. Create and Run a Task End-to-End

This is the most common workflow: create a task, run it, monitor progress, approve the plan, review changes, and merge.

# Set default codespace to avoid repeating -codespace
export AP_CODESPACE="cs_abc123"

# Create the task (optionally with a skill for specialized agent behavior)
agentpane task create -title "Add input validation to signup form" -priority high
# Or with a skill:
agentpane task create -title "Deploy VPC" -skill terraform-stacks -skill-name "Terraform Stacks" -priority high
# Output: Created task tk_xyz789

# Run the task (assigns an agent and starts planning)
agentpane task run tk_xyz789

# Check agent status
agentpane agent list

# Watch session events to monitor progress
agentpane session list -status active
agentpane session events <session-id> -limit 100

# Once the agent finishes planning, approve the plan
agentpane task approve tk_xyz789

# Monitor execution
agentpane session events <session-id> -limit 200

# When the task moves to waiting_approval, review the diff
agentpane worktree list
agentpane worktree diff <worktree-id>

# If satisfied, merge the changes
agentpane worktree merge <worktree-id> -delete -target-branch main

2. Batch Create Tasks

export AP_CODESPACE="cs_abc123"

agentpane task create -title "Fix: null pointer in user service" -priority high
agentpane task create -title "Add unit tests for auth middleware" -priority medium
agentpane task create -title "Update README with API docs" -priority low
agentpane task create -title "Refactor database connection pooling" -priority medium

3. Monitor Active Agents

export AP_CODESPACE="cs_abc123"

# See all agents and their current status
agentpane agent list

# See active sessions
agentpane session list -status active

# Get detailed events for a specific session
agentpane session events <session-id> -limit 50

4. Review and Merge Agent Work

# List all worktrees for the codespace
agentpane worktree list -codespace cs_abc123

# Review changes from a specific agent
agentpane worktree diff wt_def456

# Merge to main and clean up
agentpane worktree merge wt_def456 -delete -target-branch main

5. Manage Sandbox Environment Variables

Configure API tokens, cloud credentials, and other env vars passed to sandbox containers.

# Set a variable (value as argument)
agentpane env set AWS_REGION us-east-1

# Set a secret (pipe via stdin to avoid shell history exposure)
echo "$TFE_TOKEN" | agentpane env set TFE_TOKEN

# List all variables (values masked)
agentpane env list

# List as JSON (values unmasked — for scripting)
agentpane env list -json

# Delete a variable
agentpane env delete TFE_TOKEN

# Clear all variables
agentpane env clear

6. Scripting with JSON Output

All commands support -json for machine-readable output, enabling integration with jq and other tools.

# Get all task titles
agentpane task list -json | jq '.[] | .title'

# Get IDs of high-priority tasks
agentpane task list -json | jq '.[] | select(.priority == "high") | .id'

# Get active agent count
agentpane agent list -json | jq '[.[] | select(.status == "running")] | length'

# Get the latest session events as structured data
agentpane session events <session-id> -limit 10 -json | jq '.[] | {type: .type, timestamp: .timestamp}'

# Find worktrees with uncommitted changes
agentpane worktree list -json | jq '.[] | select(.hasChanges == true) | .id'

6. Quick Health Check Script

#!/bin/bash
if agentpane health -json | jq -e '.healthy' > /dev/null 2>&1; then
    echo "AgentPane API is up"
else
    echo "AgentPane API is DOWN" >&2
    exit 1
fi

Project Structure

The CLI source code is at cli/:

cli/
├── go.mod              # Go module definition
├── go.sum              # Dependency checksums
├── Makefile            # Build, test, lint targets
├── Dockerfile          # Multi-stage container build
├── .gitignore          # Ignore built binary
├── main.go             # Entry point (if exists)
├── sdk/                # API client library
│   ├── client.go       # HTTP client for AgentPane API
│   ├── types.go        # Request/response type definitions
│   ├── errors.go       # Error types and handling
│   └── health.go       # Health check endpoint
├── internal/           # Internal packages
│   ├── command/        # Command implementations
│   ├── logging/        # Structured logging (go-hclog)
│   └── output/         # Table and JSON output formatting
└── version/
    └── version.go      # Version constant (injected at build via ldflags)

Build and Development

Build the binary

cd cli
make build

Run tests

make test

Format and lint

make lint

Full pipeline (lint + test + build)

make all

Docker build

docker build -t agentpane-cli:latest --build-arg VERSION=1.0.0 .

Clean

make clean

Dependencies

Package	Purpose
github.com/mitchellh/cli	CLI framework (subcommands, help text, flags)
github.com/hashicorp/go-hclog	Structured logging
github.com/fatih/color	Colored terminal output

Troubleshooting

"connection refused" errors

The API server is not running. Start it:

cd .
npm run dev

The API runs on port 3001 by default.

"unauthorized" errors

Check that AP_API_TOKEN is set correctly:

echo $AP_API_TOKEN

Or pass it explicitly:

agentpane -token "ap_your_token" health

"codespace not found" errors

Verify the codespace ID:

agentpane codespace list

Build failures

Ensure Go 1.24+ is installed:

go version

If dependencies are missing, run:

cd cli
go mod tidy

Viewing raw API responses

Use -json to see the full API response for debugging:

agentpane task show <task-id> -json