CLI reference

Install the tragent CLI, scan a store from your terminal, and run it in any CI.

Install

npx needs nothing installed. The package downloads the prebuilt binary for your platform from GitHub releases and checks it against the release's SHA-256 checksums before it runs.

Terminal

$ npx @tragent/cli scan https://your-store.com

To keep the command around:

Terminal

npm i -g @tragent/cli
tragent version

macOS, Linux and Windows, on x64 and arm64. Node 18 or newer. Package: @tragent/cli on npm; source of the releases and the GitHub Action: tragent-io/cli.

Commands

scan runs on your machine and needs no account. Every other command talks to the tragent API and needs an API key from Settings › API keys. Run tragent <command> -h for its flags.

Command	What it does
tragent scan <url>	Score a URL for AI shopping readiness, on your machine. No account or key.
tragent test	Run a test plan against a store with real agents, and optionally fail the build.
tragent runs	List tests, or show one.
tragent report	Fetch a test's report as Markdown or JSON.
tragent baseline	Accept a finished test as the reference result, or show the current one.
tragent comment	Post a test's readiness summary to a pull request.
tragent fix	Show, write or propose the changes that resolve a test's findings.
tragent version	Print the CLI version.

Scan flags

Flag	What it does	Default
--feed	Product feed URL; turns on the feed-against-page checks.	—
--product-url	Product pages to inspect when the home page does not link to them.	—
--persona	Agent style to scan as.	assistant-browser
--platform	Commerce platform hint: shopify, woocommerce, magento and others.	—
--only	Comma-separated check ids to run.	—
--format	text, md or json.	text
--out	Write the report to a file.	—
--gate	Exit 1 when the scan does not pass.	—
--min-score	With --gate, the lowest passing score.	—
--watch	Scan again on an interval while you edit, for example 30s.	—
--timeout	Overall time limit for the scan.	1m

Environment variables

Variable	What it does	Default
TRAGENT_API_KEY	API key for every command except scan. Create one in Settings › API keys.	—
TRAGENT_API_URL	API root.	https://api.tragent.io
TRAGENT_SKIP_DOWNLOAD	Do not download a binary; use the tragent already on PATH.	—
NO_COLOR	Turn off colour in the output.	—

Exit codes

A build can tell a store that got worse from a tool that could not measure it.

Code	What it does
0	Passed the release check.
1	The release check failed: a stage regressed, a stage failed, or the score is under the floor.
2	Nothing was measured: bad flags, an unreachable API, or a test error. The build is not told your store broke.

GitHub Actions

tragent-io/cli@v1 installs the CLI on the runner, runs the test plan against your store and fails the job when the release check fails.

.github/workflows/tragent.yml

name: AI shopping readiness
on: pull_request

jobs:
  tragent:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: tragent-io/cli@v1
        with:
          api-key: ${{ secrets.TRAGENT_API_KEY }}
          target: https://staging.shop.example
          suite: suites/retail-core.yaml
          comment: true

Inputs

Input	What it does	Default
api-key	API key (tk_live_…), from a repository secret. Required.	—
target	The store to test: its id, or the base URL of a store you have added. Required.	—
suite	Path to a test plan YAML in this repository.	—
suite-id	Id of a test plan stored in tragent, instead of suite.	—
project	Project id, slug or name. Optional when the organisation has one project.	—
kind	checks for a quick store check, test for an AI shopping test.	—
gate	Fail the job when the release check fails.	true
wait	Wait for the test to finish. Needed for gating and the report.	true
comment	Post the result on the pull request. Needs pull-requests: write.	false
timeout	How long to wait for the test.	30m
version	CLI release to install: latest or a tag such as v0.1.2.	latest
report-path	Where to write the Markdown report.	tragent-report.md
api-url	API root.	https://api.tragent.io

Outputs

Output	What it does
run-id	The test's id.
score	AI shopping readiness, 0 to 100; empty when the test produced none.
status	passed, warned, failed or errored.
gate	passed or failed.
report-path	The Markdown report this step wrote.

GitLab CI

.gitlab-ci.yml

include:
  - remote: 'https://raw.githubusercontent.com/tragent-io/cli/v1/gitlab/.tragent.yml'

tragent:agent-readiness:
  variables:
    TRAGENT_TARGET: https://staging.shop.example
    TRAGENT_SUITE: suites/retail-core.yaml

Variable	What it does	Default
TRAGENT_API_KEY	API key, as a masked and protected CI/CD variable. Without it the job skips itself.	—
TRAGENT_TARGET	The store to test: its id or base URL. Required.	—
TRAGENT_SUITE	Path to a test plan YAML in the repository.	—
TRAGENT_SUITE_ID	Id of a stored test plan, instead of TRAGENT_SUITE.	—
TRAGENT_PROJECT	Project id, slug or name.	—
TRAGENT_KIND	checks or test.	—
TRAGENT_GATE	Fail the job when the release check fails.	true
TRAGENT_TIMEOUT	How long to wait for the test.	30m
TRAGENT_REPORT_PATH	Where to write the Markdown report.	tragent-report.md
TRAGENT_CLI_VERSION	CLI release to install.	latest
TRAGENT_API_URL	API root.	https://api.tragent.io

Any other CI

Install the package, or download the binary for the runner from the releases page, and call it. The exit code is the result.

Terminal

npx -y @tragent/cli test \
  --target https://staging.shop.example \
  --suite suites/retail-core.yaml \
  --gate