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.

CommandUse
report listList reports, most recently changed first.
report getPrint one report's metadata, linked Context objects and body.
report createCreate a report: a written document with a title and an optional body. To save a single SQL query, use insight create.
report editChange the title, description or whole body.
report appendAdd markdown to the end of the body.
report blocksList 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 archiveArchive one report. Nothing is deleted.
report sharePrint the report's public link, creating it if needed.
report unshareRevoke the report's public link.
report version-selection-rate-evidence-sourcesList what an A/B Comparison block can name.
report selection-rate-sourcesList 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 / flagWhat it does
--limit <N>Reports per page (default 50, max 200).
--cursor <CURSOR>Continue from the nextCursor of an earlier page.
--include-archivedAlso list archived reports. Off by default, so a page holds active reports only; pass it on every page of one listing.
--jsonPrint {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 / flagWhat it does
<REPORT_ID>Required. Report id from report list.
--jsonPrint {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 / flagWhat 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.
--jsonPrint {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 / flagWhat 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.
--jsonPrint {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 / flagWhat 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.
--jsonPrint {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":{}}
```
EOF

report 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]
SubcommandWhat it does
kindsList 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 / flagWhat it does
<REPORT_ID>Required. Report id from report list.
--jsonPrint {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> | pbcopy

report 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 / flagWhat it does
<REPORT_ID>Required. Report id from report list.
--yesSkip the confirmation. Required when stdin is not a terminal.
--jsonPrint {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 / flagWhat 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.
--jsonPrint {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":{}}
```
BLOCK

report 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 / flagWhat 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>