ax report
List, read, create, edit, append to, add blocks to, archive and share your organization's reports.
Reports are markdown documents your organization writes together.
ax report reads and writes them from a shell or a script: the body travels
as markdown in the report document format, so
get prints what an editor would show and append takes what you would type.
| Command | Use |
|---|---|
report list | List reports, most recently changed first. |
report get | Print one report's metadata, linked Context objects and body. |
report create | Create a report: a written document with a title and an optional body. To save a single SQL query, use insight create. |
report edit | Change the title, description or whole body. |
report append | Add markdown to the end of the body. |
report blocks | List block kinds, print one kind's schema, add a block from JSON, list a report's blocks, and update, remove or move one block by ID. |
report archive | Archive one report. Nothing is deleted. |
report share | Print the report's public link, creating it if needed. |
report unshare | Revoke the report's public link. |
report version-selection-rate-evidence-sources | List what an A/B Comparison block can name. |
report selection-rate-sources | List the references a selection-rate block can use. |
All commands accept --org <ORG_ID>; every command except archive and
blocks schema (always JSON) accepts --json, which prints the same lowerCamelCase JSON the
HTTP API returns. <REPORT_ID> is the UUID from
report list. Bodies are read from --body-file <PATH> or from stdin with
--body-file -. Arguments marked required must be supplied; everything
else is optional.
report list
List reports: id, title, when and by whom it last changed. Bodies are not fetched.
ax report list| Argument / flag | What it does |
|---|---|
--limit <N> | Reports per page (default 50, max 200). |
--cursor <CURSOR> | Continue from the nextCursor of an earlier page. |
--include-archived | Also list archived reports. Off by default, so a page holds active reports only; pass it on every page of one listing. |
--json | Print {reports, nextCursor} instead of a table. Archived reports carry archivedAt. |
On a terminal the table ends with the --cursor command for the next page when
one exists. Piped output is headerless tab-separated rows with RFC 3339
timestamps.
report get
Print one report: a metadata block, its linked Context objects, a blank line,
then the body as stored. view is an alias of get.
ax report get <REPORT_ID>| Argument / flag | What it does |
|---|---|
<REPORT_ID> | Required. Report id from report list. |
--json | Print {report}, plus contextLinks and bodyMarkdown when they are not empty. report.publicUrl is the report's public link, or null when it has none. |
Context links lists one object per line: its kind, name and id. These are
the report's Context properties in the editor. An object that was archived or
deleted shows (unavailable) (no name in --json); remove it by id.
Link and unlink objects with ax context links using a report
source, {"source":{"kind":"reports","name":"<TITLE>"},...}.
When the report has a public link, the metadata block includes a
Public link: <URL> line. Keep report.updatedAt from the output; edit needs it.
report create
Create a report from a title, with an optional description and body.
ax report create "<TITLE>" --description "<TEXT>" --body-file report.md| Argument / flag | What it does |
|---|---|
<TITLE> | Required. Plain text. Surrounding whitespace is trimmed; blank is refused. |
--description <TEXT> | One-paragraph summary shown under the title, in plain text. |
--body-file <PATH | -> | Initial body as Markdown. Omit for an empty report. |
--json | Print {report, bodyMarkdown} instead of the receipt. |
The receipt prints the new id and its updatedAt.
The title and description are plain text. Markdown headings, lists, quotes, code
fences, emphasis and links in either are refused with an error that names the
field; inline code is allowed. Put formatting in the body.
report edit
Change the title, the description and/or the whole body. At least one of
--title, --description, --body-file is needed.
ax report edit <REPORT_ID> --expected-updated-at <UPDATED_AT> --title "<TEXT>"| Argument / flag | What it does |
|---|---|
<REPORT_ID> | Required. Report id from report list. |
--expected-updated-at <RFC3339> | Required. The updatedAt you last read. |
--title <TEXT> | New title, in plain text; blank is refused. |
--description <TEXT> | New description, in plain text. Pass an empty string to clear. |
--body-file <PATH | -> | Replacement for the whole Markdown body. An empty file clears it. |
--json | Print {report, bodyMarkdown} instead of the receipt. |
When the report changed since the stamp you passed, the command fails without
writing and tells you to report get it again. To add content without
replacing the body, use report append.
Examples:
# Rewrite the body from a file, guarded by the stamp you last read
STAMP=$(ax report get <REPORT_ID> --json | jq -r .report.updatedAt)
ax report edit <REPORT_ID> --body-file report.md --expected-updated-at "$STAMP"
# Clear the description
ax report edit <REPORT_ID> --description "" --expected-updated-at "$STAMP"report append
Append markdown to the end of the body, after a blank line, leaving what is there untouched. Members with the report open see the addition.
ax report append <REPORT_ID> --body-file finding.md| Argument / flag | What it does |
|---|---|
<REPORT_ID> | Required. Report id from report list. |
--body-file <PATH | -> | Markdown to append (default -, stdin). Blank input is refused. |
--expected-updated-at <RFC3339> | Refuse the append when the report changed since this stamp. Omit to append to the body as it stands. |
--json | Print {report, bodyMarkdown} instead of the receipt. |
Examples:
# A finding from stdin
printf '> [!FINDING] Slower on Fridays\n> The p95 doubles after 16:00 UTC.\n' | ax report append <REPORT_ID>
# A live chart from an experiment's Results tab
cat <<'EOF' | ax report append <REPORT_ID>
```ax-block
{"kind":"insight","experimentId":"<EXPERIMENT_ID>","block":"scatter","scope":{},"view":{}}
```
EOFreport blocks
Add one structured block, such as a chart, Sources or a Next action, from a
JSON request instead of writing an ax-block fence by hand. The platform
checks the block against its kind's schema before saving it. These are the
same kinds and schemas the MCP report_block_kinds, report_block_schema and
report_add_block tools use. Text, headings and lists stay in the markdown
body: use report edit or report append.
ax report blocks kinds [--json]
ax report blocks schema <KIND>
ax report blocks add <REPORT_ID> --file <PATH|-> [--after <BLOCK_ID>] [--json]
ax report blocks list <REPORT_ID> [--json]
ax report blocks update <REPORT_ID> <BLOCK_ID> --file <PATH|-> [--json]
ax report blocks remove <REPORT_ID> <BLOCK_ID> [--json]
ax report blocks move <REPORT_ID> <BLOCK_ID> --after <BLOCK_ID> [--json]| Subcommand | What it does |
|---|---|
kinds | List every block kind a new block can use as KIND, LABEL, MENU and USE (what it shows). MENU is yes for the kinds the editor's / menu offers; the others stay editable in reports that already hold them, so use a menu kind for a new block when one fits. Retired kinds are left out; --json adds whenToUse, sources, figures, inMenu and a valid example block for each kind. |
schema <KIND> | Print the JSON Schema add accepts for one kind, with a valid example, the sources it reads and grounding guidance. |
add <REPORT_ID> --file <PATH|-> | Add one block from a JSON file or stdin, at the end of the report or after --after <BLOCK_ID>. Prints the new block ID. --expected-updated-at <RFC3339> refuses the add when the report changed since that stamp. |
list <REPORT_ID> | List the report's blocks in order as POS, BLOCK ID, KIND and a text preview. --json prints {reportId, updatedAt, blocks}. |
update <REPORT_ID> <BLOCK_ID> --file <PATH|-> | Replace one block in place with a block from JSON, in the same shape add takes and checked the same way. A block in a column or a Details group stays there. Prints the block's new ID, or points to list when the saved report does not identify it unambiguously. |
remove <REPORT_ID> <BLOCK_ID> | Remove one block. A Details group's opening block removes the whole group. |
move <REPORT_ID> <BLOCK_ID> --after <BLOCK_ID> | Move one block after another without changing it. Prints the block's new ID, or points to list when the saved report does not identify it unambiguously. |
update, remove and move take --expected-updated-at <RFC3339> the way
add does: when given, the change is refused if the report changed since
that stamp; when omitted, the change applies to the report as it stands. None
of them can change the report title.
The request is the block itself. Structured blocks wrap their payload in an
ax-block envelope whose block.kind is the kind from kinds:
{
"kind": "ax-block",
"block": {
"kind": "sources",
"label": "Sources",
"sources": [
{ "contextKind": "use-cases", "id": "<USE_CASE_ID>" },
{ "type": "authored", "text": "Customer interviews, October 2026" }
]
}
}A refused block writes nothing. When a known kind fails its schema, the error
names the kind, lists each failing field on its own line and points to
ax report blocks schema <KIND>; a missing or unknown kind names the closest
kinds and points to ax report blocks kinds. The MCP report_add_block tool
and the API return the same field lines:
Block kind "sources" is invalid:
sources[1].text · "text" is missing.
sources[1].txt · Not a field here.
`ax report blocks schema sources` prints every field it accepts.report create, report edit and report append check the ax-block fences
a body adds or changes, for kinds ax report blocks kinds lists. A fence the
report cannot read as its kind, such as a box-whisker block with no fields,
fails with the same error as blocks add and nothing is saved. A fence the
report already held saves as it is, even when moved.
blocks add, blocks update and those body writes also refuse a new chart
marked "configuration": "unconfigured" or with an empty data series, such as
a donut with no segments or a waterfall with no steps, and name the empty
field.
A Next action or Recommendation card added or updated here stays
unconfigured: only the MCP report tools and AX Agent can set its actions,
so kinds and schema leave them out of the example, and a block that
includes them is refused with an error naming actions.
A block ID such as
2:1wbfc9p names a block by its position and content, so read fresh IDs with
list after the report changes.
Examples:
# Pick a kind, then start from its example
ax report blocks kinds
ax report blocks schema sources | jq .example > sources.json
# Add it at the end, then another block after it
ax report blocks add <REPORT_ID> --file sources.json
ax report blocks add <REPORT_ID> --file - --after <BLOCK_ID> < next-action.json
# Change one block by ID without rewriting the body
ax report blocks update <REPORT_ID> <BLOCK_ID> --file - < sources.json
ax report blocks move <REPORT_ID> <BLOCK_ID> --after <BLOCK_ID>
ax report blocks remove <REPORT_ID> <BLOCK_ID>report archive
Archive a report. The report keeps its body, its follows and its Context links;
it leaves report list unless --include-archived is passed, and report get
still prints it with an Archived line. Nothing is deleted, and archiving an
archived report changes nothing. No confirmation prompt. ax report delete
still runs archive and prints a one-line notice that delete is now
archive; reports have no hard delete.
ax report archive <REPORT_ID>report share
Print the report's public link, creating one if the report has none. A report has at most one public link, so sharing again prints the same URL.
ax report share <REPORT_ID>| Argument / flag | What it does |
|---|---|
<REPORT_ID> | Required. Report id from report list. |
--json | Print {reportId, url, created, createdAt}. created is false when the link already existed. |
Only the URL goes to stdout; Created a public link. or Existing public link.
goes to stderr. Read-only API keys are refused.
Examples:
# Copy the report's public link to the clipboard (macOS)
ax report share <REPORT_ID> | pbcopyreport unshare
Revoke the report's public link. The old link stops working, and a later
report share creates a new one. A report without a public link succeeds with
No public link to revoke.
ax report unshare <REPORT_ID>| Argument / flag | What it does |
|---|---|
<REPORT_ID> | Required. Report id from report list. |
--yes | Skip the confirmation. Required when stdin is not a terminal. |
--json | Print {reportId, revoked}. revoked is false when the report had no public link. |
On a terminal, unshare asks you to confirm with the report's title before it
revokes the link. Read-only API keys are refused.
report version-selection-rate-evidence-sources
List the ids an A/B Comparison (version-selection-rate-evidence)
block can name for one experiment: its versions, its products with each registered
product version's fingerprint, and its selection tests. The block reads selection
counts and rates live; this command returns source identities and version run totals.
ax report version-selection-rate-evidence-sources <EXPERIMENT_ID>| Argument / flag | What it does |
|---|---|
<EXPERIMENT_ID> | Required. Experiment id from ax experiment list. |
--experiment-fingerprint <FINGERPRINT> | Read products and tests at one of the experiment's versions. Omit to read them across every version. |
--json | Print {experimentId, experimentFingerprint, experimentVersions, products, tests}. Every field is printed; an empty experimentFingerprint means every version. |
A fingerprint that is not one of the experiment's versions, or an experiment with no registered version, fails with the reason and prints nothing.
Examples:
# Product versions and selection tests across every version
ax report version-selection-rate-evidence-sources <EXPERIMENT_ID>
# Compare two product versions in a report
cat <<'BLOCK' | ax report append <REPORT_ID>
```ax-block
{"kind":"version-selection-rate-evidence","experimentId":"<EXPERIMENT_ID>","productId":"<PRODUCT_ID>","baselineVersionFingerprint":"<BASELINE_FINGERPRINT>","newVersionFingerprint":"<NEW_FINGERPRINT>","testName":"<SELECTION_TEST_NAME>","scope":{}}
```
BLOCKreport selection-rate-sources
List the references a selection-rate block is configured with for one
experiment: its versions, the tests registered at one version, and the values
each scope filter may hold. Nothing is measured; a configured block reads its
rates live.
ax report selection-rate-sources <EXPERIMENT_ID>| Argument / flag | What it does |
|---|---|
<EXPERIMENT_ID> | Required. Experiment ID from ax experiment list. |
--experiment-fingerprint <FINGERPRINT> | Read the tests at this version instead of the current one. |
--test-name <NAME> | Check a test name against that version. selectedTest is returned only when exactly one registered test has it. |
Use the returned experimentFingerprint for both scope.experimentFingerprint
and selection.testExperimentFingerprint, a test name for
selection.testName, and only returned values in scope filters. Run it again
for a baseline experiment. An experiment with no version in the org, or a
fingerprint that is not one of its versions, fails with the reason.
Save partial block choices immediately with configuration: "unconfigured",
using an empty string for a missing experiment ID or test name and {} for an
empty scope. Changing an experiment or version clears its previous test, scope
filters and search. Incomplete blocks do not query measurements; the marker is
removed when the required choices are complete.
Examples:
# Tests and scope values at the current version
ax report selection-rate-sources <EXPERIMENT_ID> --json
# Is this test still registered at an older version?
ax report selection-rate-sources <EXPERIMENT_ID> \
--experiment-fingerprint <FINGERPRINT> --test-name <TEST_NAME>