ax report
List, read, create, edit, append to and delete 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 and body. |
report create | Create a report with a title and an optional body. |
report edit | Change the title, description or whole body. |
report append | Add markdown to the end of the body. |
report delete | Delete one report. |
All commands accept --org <ORG_ID>; every command except delete 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. |
--json | Print {reports, nextCursor} instead of a table. |
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, a blank line, then the body as stored.
ax report get <REPORT_ID>| Argument / flag | What it does |
|---|---|
<REPORT_ID> | Required. Report id from report list. |
--json | Print {report, bodyMarkdown}. |
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. Surrounding whitespace is trimmed; blank is refused. |
--description <TEXT> | One-paragraph summary shown under the title. |
--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.
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; blank is refused. |
--description <TEXT> | New description. Pass an empty string to clear. |
--body-file <PATH | -> | Replacement for the whole 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 delete
Delete a report and its body. Links from findings to it are removed; the findings stay. No confirmation prompt.
ax report delete <REPORT_ID>