Command line

The astra command-line tool has 15 commands. Run it without installing anything using npx -y @attentionform/astra, or install it with npm install -g @attentionform/astra to get the short astra command.

Things that work for every command

--json prints machine-readable JSON instead of text. Add it when you are scripting.
--help prints usage for the command. --version prints the version.
Commands that write a file refuse to overwrite an existing one unless you pass --force.
Exit codes: 0 success, 1 the operation failed (file missing or invalid, batch rolled back), 2 you used the command incorrectly.
In a shell pipeline such as astra validate x.docx --json | jq, use set -o pipefail so a failure is not hidden.

Commands

`inspect`

Print the document as a compact outline with node IDs.

usage

inspect <docx> [--fidelity compact|standard|full] [--section <id>] [--max-text <n>] [--width <n>] [--wrap] [--visual] [--page <n>] [--format png|jpeg] [--max-ratio <n>] [--max-uncompressed-bytes <n>]

example

astra inspect report.docx --fidelity compact

`validate`

Check the file against the Word schema without changing it. Exit code 1 means it is invalid.

usage

validate <docx> [--max-ratio <n>] [--max-uncompressed-bytes <n>] [--style-guide <name|path>]

example

astra validate report.docx --json

`sanitize`

Remove author names, comments, revision history and other metadata, and optionally redact personal data.

usage

sanitize <in.docx> <out.docx> [--client-safe] [--redact-pii] [--zero-retention] [--replacement-author <name>] [--accept-all-revisions] [--strip-comments] [--metadata-only]

example

astra sanitize draft.docx clean.docx --client-safe

`batch`

Apply edits from a JSON file, standard input, or a quick --append. All edits apply or none do.

usage

batch <docx> [<ops.json|->] [--target-text <needle> --append <text>] [--append <text>] [--out <docx>] [--force] [--sequential|--no-sequential] [--no-validate] [--schema] [--max-ratio <n>] [--max-uncompressed-bytes <n>] [--dry-run] [--backup[=<path>]] [--matrix <vars.csv>] [--reproducible|--no-reproducible] [--author <name>] [--stream [--on-error abort|continue] [--max-errors <n>]] [--style-guide <name|path>]

example

astra batch report.docx ops.json --out updated.docx

`normalize`

Repair known structural problems and tidy redundant formatting.

usage

normalize <docx> [--out <docx>] [--dry-run] [--backup[=<path>]]

example

astra normalize old.docx --out clean.docx

`export`

Export to HTML, Markdown or PDF (PDF needs LibreOffice).

usage

export <docx> [--format html|markdown|md|pdf] [-o <outPath>] [--force]

example

astra export report.docx --format markdown -o report.md

`search`

Find text and print the IDs of the nodes that contain it. Case is ignored.

usage

search <docx> <query> [--limit <n>]

example

astra search report.docx "milestones"

`create`

Create a new document from a template, or from Markdown.

usage

create <out.docx> [--template report|memo|blank] [--force] [--from-md <file.md>] [--allowed-dir <dir>] [--dollar-math] [--style-guide <name|path>]

example

astra create report.docx --template report

`import`

Convert a Markdown file into a .docx.

usage

import <file.md> [-o <out.docx>] [--template report|memo|blank] [--force] [--allowed-dir <dir>] [--dollar-math] [--style-guide <name|path>]

example

astra import notes.md -o notes.docx

`stats`

Count words, paragraphs, tables and pages.

usage

stats <docx>

example

astra stats report.docx

`visual`

Render one page to a PNG or JPEG image (needs LibreOffice).

usage

visual <docx> [--page <n>] --out <render.png> [--format png|jpeg] [--force] [--max-ratio <n>] [--max-uncompressed-bytes <n>] [--allow-macros] [--strip-macros]

example

astra visual report.docx --page 1 --out page1.png

`history`

List the saved revisions of a document, newest first.

usage

history <docx> [--init|--track]

example

astra history report.docx

`preview-revert`

Show what going back a number of revisions would do, without changing the file.

usage

preview-revert <docx> [--steps <n>]

example

astra preview-revert report.docx --steps 1

`revert`

Go back a number of revisions. The revert is recorded as a new revision.

usage

revert <docx> [--steps <n>]

example

astra revert report.docx --steps 1

`redo`

Re-apply the revision that the last revert replaced.

usage

redo <docx>

example

astra redo report.docx

Usage lines are copied from the tool's own help, so they are always current. In usage lines, <angle brackets> are required and [square brackets] are optional. For long-form explanations of each option, see the CLI Guide.