ace-cli

ace-cli is the command-line interface for ACE (Agentic Commerce Engine). Use it to run the Contextual Enrichment Engine, track durable jobs, score a feed, and manage projects, experiments and webhooks without writing any code.

It is a thin wrapper over the ACE SDK, so every command maps to one documented endpoint. The long-form guide lives at ace.authoritas.com/docs/cli.

Install

npm install -g @authoritas-ace/ace-cli

Or run it without installing:

npx @authoritas-ace/ace-cli health

Node 18 or newer.

Configure

Set your base URL and key once, and every command picks them up:

export ACE_BASE_URL=https://ace.authoritas.com
export ACE_API_KEY=ace_live_your_key_here

Both can also be passed per command with --base-url and --api-key. If ACE_BASE_URL is unset the CLI falls back to http://localhost:3001, which is only useful when running ACE locally, so set it explicitly against production.

Create a key under Settings, Developer console, Keys. Everything except ace health needs one.

Check the connection

ace health
ace usage

usage shows your credit balance, rate limit, job count, and (for ace_test_ keys) the free monthly quota.

Contextual Enrichment Engine

Every enrichment command reads its JSON body from stdin, or from a file with --file.

# Generate contextual rules for a product set
ace rules --file products.json

# Generate content grounded in those rules
ace enrich-content --file content-request.json

# Run both steps in one call
echo '{"source":{"type":"inline","products":[{"id":"1","title":"Merino base layer"}]},
       "contentTypes":["product-description"]}' | ace pipeline

A product needs only id and title. Any extra keys become grounding signal.

Jobs

Large requests run asynchronously and return a job. Track it:

ace jobs list --status running
ace jobs get <id>
ace jobs wait <id> --timeout-ms 300000
ace jobs results <id> --page 1 --page-size 50
ace jobs cancel <id>

Projects

ace projects list
ace projects get <id>
ace projects create --name "Autumn catalogue"
ace projects update <id> --name "Autumn catalogue 2026"
ace projects delete <id>

Experiments

Every experiments command is project-scoped, so --project-id is required.

ace experiments list --project-id <projectId>
ace experiments get <id> --project-id <projectId>
ace experiments create --project-id <projectId> --file experiment.json
ace experiments update <id> --project-id <projectId> --file changes.json
ace experiments delete <id> --project-id <projectId>

Webhooks

ace webhooks create \
  --url https://example.com/hooks/ace \
  --events enrichment.job.succeeded,enrichment.job.failed

ace webhooks list
ace webhooks get <id>
ace webhooks update <id> --file changes.json
ace webhooks delete <id>
ace webhooks deliveries <id> --status failed --page-size 50

The URL must be https. Each subscription carries a signing secret: verify the signature header on your endpoint against it before trusting a payload.

Utilities and feeds

None of these consume credits.

ace utils language --file products.json
ace utils agentic-readiness --file products.json
ace utils review-quality --file items.json

ace feeds --project-id <projectId>

Output

Commands print the response payload as formatted JSON on stdout, so they pipe into jq cleanly. On an API error the message goes to stderr and the process exits non-zero, which makes the CLI safe to use in a build step.

ace jobs list --status failed | jq '.[].id'

License

MIT