Agents

athena agent ... covers the full agent surface. Every command requires an active workspace (see Workspaces).

Read-only

List agents

athena agent list                            # one page (limit 20)
athena agent list --limit 100                # one page, bigger
athena agent list --all                      # walk every page, output one envelope
athena agent list --group support            # filter by group
athena agent list --cursor <cursor>          # paginate manually

Output envelope:

{
  "data": [
    { "id": "019f902b-db6f-7ea4-8ef2-60a8ff5747cd", "name": "Email Drafter", "slug": "email-drafter", ... }
  ],
  "next_cursor": "eyJpZCI6..."
}

--all walks the cursor automatically and emits a single combined envelope with next_cursor: null. Capped at 10,000 results (override with ATHENA_LIST_MAX).

Get one agent

athena agent get email-drafter          # by slug
athena agent get 019f902b-db6f-7ea4-8ef2-60a8ff5747cd # by ID

The slug → ID resolution is one server-side ?slug= filter then a single fetch.

Mutations

Create from a JSON spec

athena agent create --from-spec ./drafter.json
cat drafter.json | athena agent create --from-spec -

The spec is the full agent object. The CLI runs pre-flight workflow validation before any HTTP request — see Workflows for the rules. Invalid workflows exit 2 with invalid_workflow and a multi-line message listing every violation in one pass.

Clone an existing agent

athena agent clone email-drafter --new-slug email-drafter-v2

Two-step under the hood (fetch source, post new). Atomic from the caller’s perspective — success returns the new agent JSON.

Update an agent

athena agent update email-drafter --from-spec ./update.json
athena agent update email-drafter --workflow @./new-workflow.json
athena agent update email-drafter --enable
athena agent update email-drafter --disable

Use --from-spec for the full update surface, including localized storefront, welcome, suggestion, category, tag, action, media, and credit fields. Use --workflow @file.json when you only want the draft lifecycle for workflow edits; workflow updates run the same pre-flight validation as create.

CMS context

athena agent cms-context --all

Returns the agent-building CMS context from the same API surface used by the admin UI: categories, tags, actions, skills, media, pages, components, and settings. Use this before writing specs so agent builders choose real IDs instead of inventing taxonomy or media references.

Media assets

Upload existing files to the workspace media library and attach them to storefront fields:

athena media upload ./icon.png --agent email-drafter --as avatar
athena media upload ./listing.png --agent email-drafter --as listing

Generate media through the approved agent-backed flow:

athena media generate "minimal app icon for an email drafter, no text" \
  --kind icon --agent email-drafter --as avatar

media generate never calls a direct CMS/Fal generation endpoint. It finds the selected workspace’s media-generator agent by slug and, if missing, creates a predefined generator payload before running it through normal agent execution. Use --group <group-uuid> when the generator needs to be created in a specific key-backed group.

Delete an agent

athena agent delete email-drafter

Returns {"deleted": true, "agent_id": "019f902b-db6f-7ea4-8ef2-60a8ff5747cd"} (server replies 204 No Content; the CLI synthesises the envelope).

Draft lifecycle

Agents have an immutable published version plus optional drafts. Edit freely on a draft, publish when ready.

# List drafts for an agent (1 anon draft + 0..N named drafts)
athena agent draft list email-drafter

# Create an anon draft seeded from the published version (idempotent)
athena agent draft create email-drafter

# Create a named draft seeded from "empty"
athena agent draft create email-drafter --name experiment-v3 --seed empty

# Get a specific draft
athena agent draft get email-drafter <version_id>

# Edit a draft (workflow + wizard + metadata in one patch)
athena agent draft update email-drafter <version_id> --patch @./patch.json

# Publish the draft (becomes the new live version)
athena agent draft publish email-drafter <version_id>

# Discard a draft
athena agent draft discard email-drafter <version_id>

Draft update is optimistic-lock protected — pass --expected-updated-at <RFC3339> to detect concurrent edits. On 409 the CLI exits 5 with code conflict and a hint to re-fetch + retry.

Run an agent

Lives at Run → since it has enough surface to warrant its own page (sync vs streaming, exit codes, NDJSON event shape).

Per-command schema dumps

Every subcommand supports --schema to emit its machine-readable JSON shape (args, types, defaults, exit codes) without doing the actual operation.

athena agent create --schema | jq .

Useful when wiring an AI agent that needs to discover the surface without parsing --help text.