Cloud Agents Commands

Create, manage, and run autonomous AI agents that review pull requests, execute instructions, and investigate issues in your repositories.

The Cloud Agents CLI commands let you create and manage autonomous AI agents — intelligent systems that can review pull requests, execute instructions, and investigate code issues directly from your repositories.

For a conceptual overview of Cloud Agents, see Cloud Agents.

Requirements

Personal Access Token (PAT) must include the cli scope
Accounts with outstanding dues receive 402 Payment Required
Some agent types require specific plan feature gates (returns 403 Forbidden if unavailable)

Commands on this page

Command	Description
`skytells agents ls`	List all agents
`skytells agents add`	Create a new agent
`skytells agents inspect`	View agent details
`skytells agents set`	Update an agent
`skytells agents rm`	Delete an agent
`skytells agents repos ls`	List bound repositories
`skytells agents repos add`	Bind repositories
`skytells agents repos rm`	Remove repository binding
`skytells agents runs ls`	List agent runs
`skytells agents runs inspect`	View run details
`skytells agents runs run`	Create and enqueue a new run

skytells agents ls

List all Cloud Agents owned by the authenticated user.

Syntax

skytells agents ls [--json]

Example

skytells agents ls

┌──────────────────────────────┬──────────┬────────────┐
│ Agent Name                   │ Type     │ Status     │
├──────────────────────────────┼──────────┼────────────┤
│ PR Reviewer                  │ review   │ active     │
│ Code Executor                │ execute  │ active     │
└──────────────────────────────┴──────────┴────────────┘

skytells agents add

Create a new Cloud Agent.

Syntax

skytells agents add \
  --name "My Agent" \
  --description "Agent description" \
  --type <type> \
  [--model <model_id>] \
  [--capabilities <tags>] \
  [--repos <repos>] \
  [--inactive] \
  [--json]

Arguments

Argument	Required	Description
`--name`	✅	Agent name (1–100 characters)
`--description`	✅	Agent description (1–500 characters)
`--type`	✅	Agent type: `review`, `execute`, `hybrid`, or `custom`

Options

Option	Description
`--model <model_id>`	Model to use (e.g., `gpt-4o`, `gpt-4o-mini`)
`--capabilities <tags>`	Comma-separated capability tags
`--repos <repos>`	Comma-separated repository bindings in `owner/repo` format (max 50)
`--inactive`	Create agent in inactive state (default: active)

Agent Types

Type	Description	Supported Run Types
`review`	Reviews pull requests and provides feedback	review, investigate
`execute`	Executes code modifications and refactoring tasks	execute
`hybrid`	Combines review and execution capabilities	review, execute, investigate
`custom`	Custom agent for specialized workflows	review, execute, investigate

Example

# Create a review agent
skytells agents add \
  --name "PR Reviewer" \
  --description "Automatically reviews pull requests" \
  --type review \
  --model gpt-4o \
  --repos "acme/monorepo"

# Create an execute agent with multiple capabilities
skytells agents add \
  --name "Task Executor" \
  --description "Handles refactoring and optimization" \
  --type execute \
  --capabilities "refactor,test,optimize" \
  --repos "acme/backend,acme/frontend"

# Create an inactive agent
skytells agents add \
  --name "Beta Agent" \
  --description "Testing new capabilities" \
  --type hybrid \
  --inactive

skytells agents inspect

Show full details of a Cloud Agent including configuration, status, and bound repositories.

Syntax

skytells agents inspect <agent-uuid> [--json]

Arguments

Argument	Description
`<agent-uuid>`	The unique identifier of the agent

Example

skytells agents inspect 550e8400-e29b-41d4-a716-446655440000

skytells agents set

Update an existing Cloud Agent. Only supplied fields are changed.

Syntax

skytells agents set <agent-uuid> \
  [--name <name>] \
  [--description <desc>] \
  [--type <type>] \
  [--model <model_id>] \
  [--capabilities <tags>] \
  [--repos <repos>] \
  [--active | --inactive] \
  [--json]

Arguments

Argument	Description
`<agent-uuid>`	The unique identifier of the agent

Options

Option	Description
`--name <name>`	Update agent name
`--description <desc>`	Update agent description
`--type <type>`	Change agent type
`--model <model_id>`	Change the model
`--capabilities <tags>`	Update capability tags
`--repos <repos>`	Replace repository bindings
`--active`	Activate the agent
`--inactive`	Deactivate the agent

Important: System agents cannot be modified. Changing type to one requiring a plan feature gate is rejected if your plan doesn't include it.

Example

# Rename an agent
skytells agents set 550e8400-e29b-41d4-a716-446655440000 \
  --name "Updated Reviewer"

# Activate a deactivated agent
skytells agents set 550e8400-e29b-41d4-a716-446655440000 --active

# Update repositories
skytells agents set 550e8400-e29b-41d4-a716-446655440000 \
  --repos "acme/repo-a,acme/repo-b,acme/repo-c"

skytells agents rm

Delete a Cloud Agent. Associated runs are preserved with their agent_id set to null.

Syntax

skytells agents rm <agent-uuid> [-f | --force]

Arguments

Argument	Description
`<agent-uuid>`	The unique identifier of the agent to delete

Options

Option	Description
`-f, --force`	Skip confirmation prompt

Example

# Delete with confirmation
skytells agents rm 550e8400-e29b-41d4-a716-446655440000

# Force delete without confirmation
skytells agents rm 550e8400-e29b-41d4-a716-446655440000 --force

Repository Bindings

Manage which repositories an agent can access and operate on.

skytells agents repos ls

List all repositories bound to an agent.

Syntax

skytells agents repos ls <agent-uuid> [--json]

Example

skytells agents repos ls 550e8400-e29b-41d4-a716-446655440000

┌───────────────────┐
│ Repository        │
├───────────────────┤
│ org/repo-a        │
│ org/repo-b        │
└───────────────────┘

skytells agents repos add

Add one or more repositories to an agent's binding list. Duplicates are ignored automatically.

Syntax

skytells agents repos add <agent-uuid> <repo>... [--json]

Arguments

Argument	Description
`<agent-uuid>`	The agent identifier
`<repo>...`	One or more repositories in `owner/repo` format

Limits

Maximum 50 repositories per agent. Excess repositories will be rejected.

Example

# Add a single repository
skytells agents repos add 550e8400-e29b-41d4-a716-446655440000 acme/frontend

# Add multiple repositories
skytells agents repos add 550e8400-e29b-41d4-a716-446655440000 \
  acme/backend acme/frontend acme/shared-libs

skytells agents repos rm

Remove a repository from an agent's binding list.

Syntax

skytells agents repos rm <agent-uuid> <repo> [--json]

Arguments

Argument	Description
`<agent-uuid>`	The agent identifier
`<repo>`	Repository in `owner/repo` format

Example

skytells agents repos rm 550e8400-e29b-41d4-a716-446655440000 acme/old-repo

Runs

Create and manage agent runs — execution instances of your agents.

skytells agents runs ls

List runs across all agents, or filter by agent, status, and trigger source.

Syntax

skytells agents runs ls \
  [--agent <agent-uuid>] \
  [--status <status>] \
  [--run-type <type>] \
  [--trigger <source>] \
  [--page <n>] \
  [--per-page <n>] \
  [--json]

Options

Option	Description
`--agent <id>`	Filter to a specific agent (UUID)
`--status <status>`	Filter by status: `queued`, `running`, `awaiting_approval`, `approved`, `completed`, `failed`, `cancelled`
`--run-type <type>`	Filter by run type: `review`, `execute`, `investigate`
`--trigger <source>`	Filter by trigger: `github`, `console`, `slack`, `chat`
`--page <n>`	Page number (default: 1)
`--per-page <n>`	Results per page, max 100 (default: 20)

Example

# List all runs
skytells agents runs ls

# List runs for a specific agent
skytells agents runs ls --agent 550e8400-e29b-41d4-a716-446655440000

# Filter by status and type
skytells agents runs ls --status completed --run-type review

# List failed runs
skytells agents runs ls --status failed

# Paginate results
skytells agents runs ls --page 2 --per-page 50

skytells agents runs inspect

Show full details of a single run, including token usage, result summary, and error information.

Syntax

skytells agents runs inspect <run-uuid> [--json]

Arguments

Argument	Description
`<run-uuid>`	The unique identifier of the run

Example

skytells agents runs inspect 7c9e6679-7425-40de-944b-e07fc1f90ae7

skytells agents runs run

Create and enqueue a new run for a Cloud Agent.

Syntax

# For review or investigate runs
skytells agents runs run <agent-uuid> \
  --type review \
  --repo <owner/repo> \
  --pr <number> \
  [--branch <branch>] \
  [--json]

# For execute runs
skytells agents runs run <agent-uuid> \
  --type execute \
  --repo <owner/repo> \
  --prompt "Task description" \
  [--branch <branch>] \
  [--json]

Arguments

Argument	Required	Description
`<agent-uuid>`	✅	The agent to run
`--type <type>`	✅	Run type: `review`, `execute`, `investigate`
`--repo <repo>`	✅	Target repository in `owner/repo` format

Options (Review & Investigate)

Option	Required	Description
`--pr <number>`	✅	Pull request number
`--branch <branch>`	—	Target branch (default: PR base branch)

Options (Execute)

Option	Required	Description
`--prompt <text>`	✅	Instruction prompt (1–4,000 characters)
`--branch <branch>`	—	Target branch to work on

Billing & Rate Limits

Billing gates are checked in order:

Daily run cap
Monthly review limit (for review and investigate types)
Monthly execute limit (for execute type)

Error Responses

Code	Meaning
402	Account suspended or payment outstanding
403	Agent is inactive or insufficient permissions
422	Validation error (missing required field, incompatible run type, etc.)
429	Daily or monthly run limit reached — upgrade your plan

Examples

# Review a pull request
skytells agents runs run 550e8400-e29b-41d4-a716-446655440000 \
  --type review \
  --repo acme/monorepo \
  --pr 123

# Execute a task
skytells agents runs run 550e8400-e29b-41d4-a716-446655440000 \
  --type execute \
  --repo acme/backend \
  --prompt "Add comprehensive error handling to the auth module" \
  --branch feature/error-handling

# Investigate an issue
skytells agents runs run 550e8400-e29b-41d4-a716-446655440000 \
  --type investigate \
  --repo acme/frontend \
  --pr 456

Workflow Examples

Create and Run a Review Agent

# Create a review agent
skytells agents add \
  --name "PR Reviewer" \
  --description "Automatically reviews pull requests" \
  --type review \
  --model gpt-4o \
  --repos "acme/monorepo"

# Trigger a review run
skytells agents runs run 550e8400-e29b-41d4-a716-446655440000 \
  --type review \
  --repo acme/monorepo \
  --pr 123

# Check run status
skytells agents runs ls --agent 550e8400-e29b-41d4-a716-446655440000 --status running

Create a Multi-Repo Execute Agent

# Create an execute agent
skytells agents add \
  --name "Code Refactorer" \
  --description "Handles code refactoring tasks across services" \
  --type execute \
  --model gpt-4o \
  --capabilities "refactor,optimize,security-hardening" \
  --repos "acme/backend,acme/frontend"

# Add more repositories later
skytells agents repos add 550e8400-e29b-41d4-a716-446655440000 acme/shared-libs

# Execute a refactoring task
skytells agents runs run 550e8400-e29b-41d4-a716-446655440000 \
  --type execute \
  --repo acme/backend \
  --prompt "Refactor all database queries to use prepared statements"

References

Source: Skytells CLI GitHub Repository
Related: See Authentication for PAT setup and required scopes

How is this guide?

On this page