CLI

Build, check, preview and publish guidance from your terminal or from CI with the cueston command line.

The cueston CLI uses the same API as the dashboard. Your role, plan limits, approval rules and the audit log apply exactly as they do there. Everything you create or edit is a draft until you publish it.

Install

Shell

npm install -g cueston
cueston --version

Or run it without installing:

Shell

npx cueston tours list

It needs Node.js 20 or later.

Shell

cueston login

login shows a short code and opens your browser. Check that the code matches, pick the workspace and approve. The CLI then saves a secret API key (Cueston CLI · <your computer>) that acts as you, with your role. Revoke it any time in Settings → API keys.

On a remote machine, use cueston login --no-browser and open the link yourself.
To use a key you already have: cueston login --key sk_…, or echo "$KEY" | cueston login --with-key.
cueston whoami shows who you are, the workspace, your role and the API URL.
cueston logout forgets the key on this computer. cueston logout --revoke also revokes it.

The key is stored in ~/.config/cueston/config.json (or $XDG_CONFIG_HOME/cueston/), readable only by you. Set CUESTON_CONFIG_DIR to use another folder.

Which key and URL a command uses

Setting	Order
Key	`--key` → `CUESTON_API_KEY` → saved by `cueston login`
API URL	`--api-url` → `CUESTON_API_URL` → saved by `cueston login` → `https://app.cueston.com`

Guidance

Every content type has the same commands. Use the plural or singular name: tours or tour, tooltips, banners, checklists, surveys, announcements.

Shell

cueston tours list                        # id, name, status (live, staging, draft), URL pattern
cueston tours list --status live
cueston tours get 12                      # every field, as YAML (--json for JSON)
cueston tours create --file tour.yaml     # a draft; JSON or YAML; --file - reads stdin
cueston tours create --name "Welcome" --url-pattern "https://app.acme.com/*"
cueston tours update 12 --name "Welcome v2"
cueston tours update 12 --data '{"steps":[{"selector":"#new","title":"New","content":"…"}]}'
cueston tours duplicate 12
cueston tours delete 12 --yes

Field flags (--name, --url-pattern) win over --file and --data. To see every field a type takes, run cueston tools list --schema create_tour.

Publish, roll back, review

Shell

cueston tours publish 12                              # to production
cueston tours publish 12 --env staging --note "New export step"
cueston tours unpublish 12
cueston tours versions 12
cueston tours rollback 12 345                         # make version id 345 live again
cueston tours restore 12 345                          # copy version 345 into the draft
cueston tours request-review 12 --note "Ready for launch"

If your workspace requires approval, publish to production fails with approval_required. Use request-review instead; a publisher approves it in Approvals or with cueston reviews approve.

Shell

cueston reviews list                      # pending; --status all for every request
cueston reviews approve 7
cueston reviews reject 7 --note "Shorten step 2"
cueston reviews cancel 7                  # your own request

Surveys

Shell

cueston surveys results 4 --days 90       # responses, response rate, NPS, answers
cueston surveys export 4 -o responses.csv

Audiences, analytics, translations, previews, webhooks

Shell

cueston segments list
cueston segments create --file segment.yaml
cueston segments update 3 --description "Admins on Pro"
cueston segments estimate 3               # matching users from the last 30 days
cueston segments estimate --file rules.yaml
cueston segments delete 3 --yes

cueston analytics                         # workspace totals and top guidance, last 30 days
cueston analytics --days 7
cueston analytics item tour 12            # totals and the step funnel
cueston analytics issues                  # tooltips and steps whose element went missing
cueston analytics export events -o events.csv

cueston translations export --languages de,fr -o strings.csv     # or --format xliff
cueston translations import strings.csv                          # shows what would change
cueston translations import strings.csv --apply                  # writes it (to drafts)
cueston translations auto tour 12 --to de,fr                     # machine-translate every step

cueston preview tour 12 --site-url https://app.acme.com/billing  # a link that shows the draft

cueston webhooks list
cueston webhooks create --url https://example.com/hooks --events content.published
cueston webhooks test 5
cueston webhooks delete 5 --yes

Content as code

Keep guidance in git and ship it from CI.

Shell

cueston pull                     # writes ./cueston/<type>/<id>-<name>.json
cueston pull content --type tours,banners
# edit the files, or add a new file without "id"
cueston push --dry-run           # prints the plan
cueston push                     # creates and updates drafts
cueston push --publish --env staging

Files hold the editable draft fields, with keys in a stable order, so they diff cleanly.
A file without "id" creates a new draft. Its id is written back into the file.
A file with an id updates that item's draft. Only fields that differ are sent. Fields a file leaves out stay as they are.
After saving, push writes back what the server stored, so running it again changes nothing.
push exits with code 1 if any item failed. pull --prune removes files of deleted items.

In CI

Create a key in Settings → API keys and store it as a secret. No login needed:

.github/workflows/guidance.yml

on:
  push:
    branches: [main]
    paths: ["cueston/**"]
jobs:
  ship:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx cueston push --publish
        env:
          CUESTON_API_KEY: ${{ secrets.CUESTON_API_KEY }}

AI agents and MCP

Every MCP tool is also a CLI command:

Shell

cueston tools list
cueston tools list --schema validate_content
cueston tools call validate_content --arg type=tour --arg id=12
cueston tools call find_elements --arg query="export button"
cueston tools call debug_audience --data '{"url":"https://app.acme.com/billing","userId":"u_42"}'

Most MCP clients connect to https://app.cueston.com/api/mcp directly and sign in. For a client that only runs local (stdio) servers, cueston mcp bridges stdio to Cueston:

mcp.json

{
  "mcpServers": {
    "cueston": {
      "command": "npx",
      "args": ["-y", "cueston", "mcp"],
      "env": { "CUESTON_API_KEY": "sk_…" }
    }
  }
}

Any endpoint

Shell

cueston api GET /api/tours
cueston api PATCH /api/tours/12 --data '{"name":"Welcome"}'
cueston api GET analytics/overview -q days=7       # /api is added for you

See the REST API reference for every endpoint.

Output and exit codes

--json on any command prints one JSON document on stdout. Errors in --json mode are { "error": { "message", "code", "status", "details", "hint" } }.
Without --json, results go to stdout and progress to stderr. Colors only show on a terminal; set NO_COLOR to turn them off.
Rate-limited requests are retried after the time the server asks for.

Exit code	Meaning
`0`	Success
`1`	Failure
`2`	Wrong arguments or flags

Global options

Option	What it does
`--json`	Machine-readable output on stdout
`--key <sk_…>`	Use this API key for the command
`--api-url <url>`	Use another Cueston API, like `http://localhost:3000`
`CUESTON_API_KEY`	The API key, for CI and scripts
`CUESTON_API_URL`	The API URL
`CUESTON_CONFIG_DIR`	Where `login` stores its key
`NO_COLOR`	Turn colors off

Install

Sign in

Which key and URL a command uses

Guidance

Publish, roll back, review

Surveys

Audiences, analytics, translations, previews, webhooks

Content as code

In CI

AI agents and MCP

Any endpoint

Output and exit codes

Global options

On this page