@erdoai/cli

Erdo CLI — drive evals (and more) from the terminal or CI, over the same /v1 REST API the MCP tools use.

Install

npm install -g @erdoai/cli   # global; then run `erdo`
npx @erdoai/cli --help       # or run without installing
erdo update                  # self-update to the latest published version

Requires Node.js 22.13+. User-facing install docs: https://docs.erdo.ai/cli

When a newer version is published, every command prints one line on stderr naming the installed version and erdo update. It is on stderr so stdout stays clean JSON for scripts and agents, the published version is remembered on disk and re-checked about once a day, and an unreachable registry says nothing at all. Set ERDO_NO_UPDATE_NOTIFIER=1 to silence it. An old build's --help is correct about itself and wrong about the product — that is the failure this notice exists to stop.

Auth

Multi-account, like gh. Log in with an API key (created in Erdo); it's stored per account at ~/.config/erdo/config.json and tied to your active org.

erdo login                      # browser sign-in (mints + stores a token)
erdo login --key erdo_api_...   # headless/CI: paste an API key instead
erdo whoami                     # active account + org
erdo auth status                # all accounts (* = active)
erdo auth switch [email]        # switch active account (auto-toggles with two)
erdo logout [email]

erdo org list                   # your orgs (* = active)
erdo org use [id|slug]          # set the active org for this account
erdo --org acme eval suites     # one-off override for a single command

Env overrides for CI/scripting: ERDO_API_KEY, ERDO_ORG, ERDO_API_URL, ERDO_ACCOUNT.

Datasets

Two ways to read a dataset, and the difference matters.

datasets fetch is the read. You write the SQL, so the same command gives the same rows every time — use it for anything mechanical, scripted, or run by an agent. It answers with {columns, rows, row_count}.

erdo --org 2200-brickell datasets fetch 2200-brickell.page-events \
  --sql "SELECT event, count(*) FROM data GROUP BY 1 ORDER BY 2 DESC" --limit 20

erdo datasets fetch acme.leads --limit 50        # no SQL: just the rows
erdo datasets fetch acme.leads --filter <name>   # opt into a saved filter

The table is named data — for file datasets (CSV, Excel, and anything written by an event pipeline) that is the name regardless of the dataset's slug or resource key, and it is not guessable, so it is the first thing to get right. The columns aren't guessable either, so look before you write SQL:

erdo datasets schema acme.leads          # column names and types

datasets schema reads the stored table itself, so it shows the columns that are actually there — the ones fetch --sql can reference — rather than a declared schema that may lag what recent writes added. Database and warehouse datasets are queried through their real table names, which come from the dataset's schema. The SQL dialect is DuckDB. A dataset's default filters apply on every read; --filter <name> adds a saved filter on top, and narrows further — a named filter never bypasses a default. See erdo datasets filter list <slug> for the names a dataset offers.

datasets query is the natural-language wrapper. Erdo writes and runs the SQL for you, and answers with that SQL alongside the values, so it is the one to reach for when you don't yet know the shape of the data. It runs an agent, so it is slower and it is not deterministic — two identical questions can produce two different queries.

erdo --org 2200-brickell datasets query 2200-brickell.page-events \
  "which pages get the most views, and how many convert?"

A file dataset keeps the versions it overwrote. Its contents are stored, and each write that replaces them keeps the version it replaced, so an import that landed bad rows over good ones has not destroyed them. List the versions, then read one back with fetch — the same SQL you would run against the live table.

erdo datasets revisions acme.leads               # live version first, then superseded
erdo datasets fetch acme.leads --revision <id> \
  --sql "SELECT * FROM data"                     # query those older contents

The history is read-only: nothing here rolls a dataset back. Restoring means fetching the rows out of the old revision and writing them in again through the normal write path.

erdo datasets list                     # slug, type, status, class, name
erdo datasets upload ./leads.csv       # create a dataset from a file

Agents & pages

erdo agent ask "what was revenue last week?" --datasets sales
erdo threads create --name "landing build"       # -> thread id
erdo agent send <thread> "Build a landing page for ACME ..." --agent erdo.artifact-builder
erdo agent send <thread> "What should I do next?" --context "Current screen: checkout experiment"
erdo agent send <thread> "Summarize the existing data" --read-only

erdo pages deploy --title "ACME" --html @page.html --js @page.js --public
erdo pages list --type html_page
erdo pages get <artifact-id>

--html/--js/--css accept @path to read a file. Sending a message to a thread runs an agent — that's also how the artifact-builder produces a page from a brief. Use --read-only to limit the default erdo.data-question-answerer turn to read-only agent tools. Other agents are rejected, and the flag is omitted by default so existing sends retain their behavior.

erdo runs list --agent erdo.artifact-builder --status failed   # inspect agent runs
erdo runs get <run-id>

Evals

erdo eval suites                          # list suites (slug, agent, artifact?)
erdo eval suite landing-variations        # show a suite + its cases
erdo eval run landing-variations --watch  # run it and poll until done
erdo eval results <run-id>                # per-case scores + lenses
erdo eval runs --suite landing-variations # recent runs

# maintain the corpus
erdo eval case add landing-variations \
  --name "voice-concierge" \
  --input "Build a landing page for ACME with a voice concierge (agent id abc123) ..." \
  --rubric '[{"criterion":"voice widget loads and is on-brand","weight":2},{"criterion":"hero + form render correctly","weight":1}]'
erdo eval case rm landing-variations voice-concierge

--watch exits non-zero if the run doesn't complete cleanly, so it doubles as a CI gate.

Develop

npm install            # or yarn
npm run dev eval suites   # run from source (tsx)
npm run build:check       # typecheck
npm run build             # bundle to dist/ (bin: erdo)

Release

The version in cli/package.json is the release. Bump it in the same PR as the change (semver: feat → minor, fix → patch) and merge; .github/workflows/publish-cli.yml publishes whatever main says and tags the result. There is no tag to remember — forgetting one is how the CLI sat at npm 0.5.1 while package.json read 0.23.0 and every work-engine command was unreachable for anyone who installed it.

npm itself is the guard: an already-published version stops the job before it builds, so a cli/ change with no bump, a re-run, and a revert all no-op. A change under cli/ that ships no bump ships to nobody.