Skip to content
Athena Docs

Quickstart

This path takes you from no CLI installed to a successful agent run.

Prerequisites

  • A workspace you belong to (you’ll discover its slug in step 3)
  • An Athena account (email + password) OR an ATHENA_API_TOKEN env var
  • A published agent in that workspace (or follow Agents to create one)

  1. Install the binary (full install guide →):

    Terminal window
    curl -fsS https://fs-service.leanscale.com/athena-cli/cli/install.sh | sh
    export PATH="$HOME/.athena/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc
    athena --version

    The installer drops athena under ~/.athena/bin/, seeds a starter ~/.athena/config.toml with dev, beta, and prod profiles, and prints a PATH hint if needed. Re-running upgrades the binary; credentials.toml and config.toml are never clobbered.

  2. Log in:

    Terminal window
    athena login --email you@leanscale.com --password "$ATHENA_PASSWORD"

    Credentials persist to ~/.athena/credentials.toml (chmod 600). Subsequent commands authenticate automatically; refresh-on-401 is transparent.

  3. List the workspaces you belong to:

    Terminal window
    athena workspace list
    {
      "workspaces": [
        { "workspace_id": "019f58c6-0400-7fa2-a41f-a32abf613c76", "workspace_name": "Athena Dev", "role": "admin" }
      ]
    }

  4. Pin one as the active workspace (sticky across commands):

    Terminal window
    athena workspace use athena

  5. Run an agent:

    Terminal window
    echo '{"input":"hello"}' | athena agent run my-agent --input -

    Streaming is the default — you’ll see one JSON object per line as the workflow progresses. The last event has is_terminal: true.

What you can do next

  • List, inspect, create agents → Agents
  • Edit a draft and publish → Draft lifecycle
  • Run more workflows → Run (sync vs streaming, exit codes, NDJSON)
  • Build from a JSON spec → Workflows (validation rules, examples)

Using the CLI from an AI agent (Claude, etc.)

The CLI was designed to be invoked from another LLM-agent loop. A few agent-friendly entry points:

  • Discover the command tree as JSON: athena --schema dumps every subcommand, its args, and its exit codes as one machine-readable JSON document. No need to parse --help text.
  • Per-command schemas: athena agent run --schema, athena agent create --schema, etc. — same dump scoped to a single command.
  • Stable error envelope: every non-zero exit writes {code, message, hint, trace_id} to stderr. code is stable across versions, hint is human-readable, trace_id lets you correlate with server logs.
  • NDJSON streaming: agent run emits one JSON object per line on stdout. An agent can pipe through jq -c or read line-by-line without buffering surprises.