ace-cli

ace-cli is the command-line interface for ACE (Agentic Commerce Engine). Use it to check your feed API, list feeds, view your credit balance, generate content, and enrich product feeds—all from the terminal.

Who this is for

If you have an ACE instance (or use one provided by your team) and want to:

• Check that the feed API is up and responding
• List your feeds, optionally filtered by project
• See how many credits you have left
• Generate content (e.g. product descriptions) via the content API
• Enrich product feeds via the feed enrichment API

…then ace-cli is for you. You need an API key from your ACE app (usually under Settings → API Keys) to use everything except the health check.

Installation

Option 1: Install globally

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

Then run any command with ace (e.g. ace health, ace credits).

Option 2: Run without installing (npx)

npx @authoritas-ace/ace-cli <command>

Example: npx @authoritas-ace/ace-cli health

Configuration

The CLI talks to your ACE app using a base URL and, for most commands, an API key.

| What | Environment variable | Flag / option | Default | | ----------- | -------------------- | -------------------- | ---------------------- | | ACE base URL | ACE_BASE_URL | -b / --base-url | http://localhost:3001 | | API key | ACE_API_KEY | -k / --api-key | (none) |

You can set the environment variables once in your shell or in a .env file, or pass the options on each run.

Examples:

# Use defaults (localhost:3001, no API key)
ace health

# Point to your hosted ACE and pass API key via flag
ace --base-url https://your-ace.example.com --api-key YOUR_API_KEY credits

# Or set env vars once, then run commands
export ACE_BASE_URL=https://your-ace.example.com
export ACE_API_KEY=your_api_key_here
ace feeds
ace credits

Commands

ace health

What it does: Checks that the ACE feed API is reachable and responding.
Auth: None.
When to use: To verify the server is up or to debug connectivity.

ace health
# Or with a custom base URL
ace --base-url https://your-ace.example.com health

ace feeds

What it does: Lists your feeds. Optionally restricts the list to a single project.
Auth: API key required.
When to use: To see feed IDs and metadata, or to pick a project before other operations.

| Option | Short | Description | |--------|-------|-------------| | --project-id <id> | -p | Only list feeds for this project ID |

ace feeds
ace --api-key $ACE_API_KEY feeds
ace feeds --project-id proj_abc123

Output is JSON (array of feed objects).

ace credits

What it does: Shows the credit balance for the account associated with your API key.
Auth: API key required.
When to use: To see how many credits you have before running content generation or enrichment.

ace credits
ace -k $ACE_API_KEY credits

ace content

What it does: Sends a JSON request to the ACE content API and prints the generated content (e.g. product descriptions) as JSON.
Auth: API key required.
When to use: When you want to generate content from the command line. You supply a JSON body that matches what your ACE content API expects (e.g. type, data, and other fields).

Input: JSON either from stdin or from a file.

| Option | Short | Description | |--------|-------|-------------| | --file <path> | -f | Read the JSON body from this file instead of stdin |

# From a file
ace content --file request.json

# From stdin (e.g. a here-doc or another command)
echo '{"type":"product_description","data":{...}}' | ace content

If the request succeeds, the response is printed as formatted JSON. Errors are printed to stderr and the process exits with a non-zero code.

ace enrich

What it does: Sends a JSON payload to the ACE feed enrichment API and prints the enriched result as JSON.
Auth: API key required.
When to use: When you want to enrich a product feed (e.g. complete missing fields, normalize data) from the command line. You supply a JSON body in the format your ACE feed enrichment API expects (typically an object with a products array and optional config or options).

Input: JSON either from stdin or from a file.

| Option | Short | Description | |--------|-------|-------------| | --file <path> | -f | Read the JSON body from this file instead of stdin |

# From a file
ace enrich --file feed-payload.json

# From stdin
cat my-products.json | ace enrich

If the request succeeds, the enriched data is printed as formatted JSON. Errors are printed to stderr and the process exits with a non-zero code.

Quick reference

| Command | Auth | Purpose | |---------|------|--------| | ace health | No | Check feed API health | | ace feeds | API key | List feeds (optional -p / --project-id) | | ace credits | API key | Show credit balance | | ace content | API key | Generate content (stdin or --file) | | ace enrich | API key | Enrich a product feed (stdin or --file) |

Global options (before the command): -b, --base-url <url> · -k, --api-key <key>

Getting help

• Run ace --help for global options and list of commands.
• Run ace <command> --help for options of a specific command (e.g. ace content --help).