ora — the ora CLI

Drive the ora public API from your terminal. Every command is generated from ora's public OpenAPI document, so the CLI always matches the API: https://api.agentfront.sh/openapi.json.

Install

npm install -g @ora-ai/cli
ora --help

(npx @ora-ai/cli also works. Note: bare npx ora fetches an unrelated npm spinner library — always use the scoped package name with npx.)

Interactive

Just run ora — browse every command, get prompted for arguments, and see the equivalent scriptable command before it runs.

ora

This only opens in a real terminal (both stdin and stdout attached to a tty). Piped or scripted (ora | less, ora > out.txt, inside CI), bare ora prints --help instead — nothing changes for existing scripts.

Authenticate

Mint an api key in the ora dashboard (Settings → API keys), then:

ora login            # paste the key (masked), or:
ora login --api-key ora_sk_...
ora whoami

In CI, skip login and export ORA_API_KEY (prefer short-expiry keys). The key is stored at ~/.config/ora/config.json (0600) and exchanged for a short-lived token on every call — the key itself never travels beyond the token exchange.

Point the CLI at an environment (--api-url)

By default the CLI talks to the URL embedded in its spec (https://api.agentfront.sh). To target staging, a dev cluster, or any self-hosted ora, set the API base once at login — it's remembered in ~/.config/ora/config.json:

ora login --api-url https://api.staging.agentfront.sh   # staging
ora login --api-url http://api.localhost:8081           # local k3d dev

Precedence for every command: --api-url flag > ORA_API_URL env > config.json > the spec's default. So one-off calls can override without re-logging-in:

ora tunnels list --api-url https://api.staging.agentfront.sh
ORA_API_URL=https://api.staging.agentfront.sh ora whoami

Tunnels — expose your localhost to ora (like ngrok http)

Let ora's scans and journeys reach a dev site running on your machine. One command, prints a working URL, forwards until Ctrl-C:

ora tunnel 3000

🚇 ora tunnel — dev-3000
forwards   localhost:3000 → 924649e0…
url        https://924649e0-….t.agentfront.sh/?ora_token=ora_tt_…
           only holders of this link reach it — paste it as a journey targetDomain
● connected — Ctrl-C to stop
200 GET    / 8ms

The port is chosen here, at connect time — the server can only ask your connected CLI to fetch; it never reaches into your machine. Re-running ora tunnel 3000 reuses the same tunnel (and URL): the per-tunnel secret is remembered in ~/.config/ora/tunnel-secrets.json (0600), like ngrok's authtoken.

Access modes (--access)

ora tunnel 3000                       # protected (default): the printed
                                      # link works; strangers get 404
ora tunnel 3000 --access public       # open URL — answer engines can
                                      # browse/index the dev site
ora tunnel 3000 --access private      # no URL; only ora's own scanners

| mode | who reaches https://<id>.t.<domain> | use it for | |---|---|---| | protected | holders of the printed link (?ora_token=… or an X-Ora-Tunnel-Token header) | journeys, sharing with a teammate | | public | anyone — no credential | letting real answer engines measure the dev site | | private | nobody — 404; only ora's in-cluster scanners via tunnel://<id>/ | scan-only workflows |

Everything else answers 404 identically (a private tunnel is indistinguishable from a nonexistent one), revoked answers 410, and a tunnel whose CLI isn't currently connected answers 502 TUNNEL_NOT_CONNECTED.

Point a run at your tunnel

• Journey: create the tunnel --access public, then use the hostname as the journey's targetDomain — e.g. 924649e0-….t.agentfront.sh. The agent browses it like any site.
• Audit (the agent-readiness audit at ora.ai): create the tunnel --access public and let ax run it end to end — ax audit localhost:<port> --tunnel-cmd 'ora tunnel <port> --access public' (npm ax; ax audit localhost:<port> --tunnel ora does the same with just ORA_API_KEY). tunnel://<id>/ targets are for ora's in-cluster scanners only, not a public API.

Manage tunnels

ora tunnels list             # status-glyph table (● connected ✖ revoked …)
ora tunnels get <id>
ora tunnels revoke <id>      # kill the live connection, keep the row
ora tunnels delete <id>      # revoke + remove the row entirely

Quick local target to test with:

node -e 'require("http").createServer((q,r)=>{r.writeHead(200,{"content-type":"text/html"});r.end("<h1>it works</h1>")}).listen(3000)'
ora tunnel 3000    # then open the printed url

Use

Every command's --help ends with a ready-to-run example (including a request body where one is needed) — the fastest way to learn a command is to ask it:

ora --help                             # all command groups
ora experiment runs --help             # everything you can do with runs
ora experiment runs create --help      # flags + an example run.json

Runs — launch and follow agent executions

ora experiment runs list --page-size 20

cat > run.json <<'EOF'
{ "intent": "check pricing for acme.com", "harness": "eve", "model": "claude-sonnet-5" }
EOF
ora experiment runs create --file run.json           # returns {runId, streamUrl, status}
ora experiment runs create --file run.json --watch   # same, then streams live events until done
ora experiment runs stream <run-id>                  # attach to a run already in flight
ora experiment runs feed                             # org-wide live feed of run status changes

After a run completes, read its artifacts:

ora experiment runs insight <run-id>       # the analyzed outcome
ora experiment runs trajectory <run-id>    # step-by-step trace
ora experiment runs raw-trace <run-id>     # the full raw event log

Intents — AEO measurement (studio)

ora intents list
cat > intent.json <<'EOF'
{ "title": "Best AEO platform for B2B SaaS", "layer": "discovery" }
EOF
ora intents create --file intent.json
ora intents measurements-status                # are the daily measurements running?
ora intents measurements-pause-all             # stop the scans
ora intents measurements-resume-all            # restart them

Sessions — long-lived agent environments

ora sessions catalog        # harnesses + models you can launch
ora sessions list
ora sessions hibernate <id>
ora sessions wake <id>

Scripting

--json prints the raw API response; with --watch it becomes NDJSON (the create response first, then one line per event). Exit codes: 0 ok, 1 API/auth error, 2 usage error.

id=$(ora experiment runs create --file run.json --json | jq -r .runId)
ora experiment runs stream "$id" --json | jq -c 'select(.event == "step")'

ora experiment runs list --json | jq '.results[] | {id, harness, status}'

In CI, export ORA_API_KEY instead of logging in. Point at another environment with ORA_API_URL or --api-url.

Errors that explain themselves

• 402 — a plan limit was hit; the message names the dimension and where to upgrade.
• 403 INSUFFICIENT_SCOPE — the key lacks a scope; the message names it. Mint a key with that scope and ora login again.