Recipes

Short, working examples for common jobs. They use the command-line tool; every one has an MCP equivalent in MCP tools.

Change a paragraph you found by its text

Search returns the ID of each matching node. Use that ID as the target of an edit.

shell

npx -y @attentionform/astra search report.docx "Draft status"
# prints:  <ID> <the matching paragraph text>

echo '[{"action":"replace","target":"<ID>","text":"Status: final"}]' | npx -y @attentionform/astra batch report.docx -

Add a paragraph to the end without knowing any ID

shell

npx -y @attentionform/astra batch report.docx --append "Prepared for the board meeting."

Try an edit without changing the file

--dry-run checks the operations and reports the result without writing. --backup keeps a copy before a real edit.

shell

npx -y @attentionform/astra batch report.docx ops.json --dry-run
npx -y @attentionform/astra batch report.docx ops.json --backup

Build a document from Markdown

shell

npx -y @attentionform/astra create spec.docx --template blank --from-md spec.md
# or convert a file you already have:
npx -y @attentionform/astra import notes.md -o notes.docx

Headings, lists, tables, code blocks and equations are converted to native Word content. Dollar signs are treated as math only if you pass --dollar-math, so prices and shell snippets are left alone.

Export

shell

npx -y @attentionform/astra export report.docx --format markdown -o report.md
npx -y @attentionform/astra export report.docx --format html -o report.html
npx -y @attentionform/astra export report.docx --format pdf -o report.pdf   # needs LibreOffice

Remove identifying information before you share a file

shell

npx -y @attentionform/astra sanitize draft.docx public.docx               # metadata, authors, comments, revision history
npx -y @attentionform/astra sanitize draft.docx client.docx --client-safe # also redacts emails, phone numbers and similar in the text
npx -y @attentionform/astra sanitize draft.docx legal.docx --metadata-only # metadata only; keeps comments and tracked changes

Without --client-safe or --redact-pii, the text of the document is kept as it is, and ASTra prints a warning to say so. Redaction finds common patterns only; always read the result before you send it.

Turn on revision history for a document

shell

npx -y @attentionform/astra history report.docx --init     # record the current file as the starting point
npx -y @attentionform/astra history report.docx            # list recorded revisions, newest first

See Core concepts for how revisions are recorded, and the preview-revert, revert and redo commands in Command line.

Fail a CI job when a Word file is invalid

validate checks one file per call and exits with code 1 when the file is invalid, so a small loop covers a folder:

.github/workflows/validate-docs.yml

name: Validate Word documents
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Validate every .docx under docs/
        run: find docs -name '*.docx' -print0 | xargs -0 -r -n1 npx -y @attentionform/astra validate

Brief an AI agent

Most MCP clients need no instructions. A short prompt like this helps weaker models stay on track:

prompt

You have the ASTra MCP tools. Open the .docx I name with open_document, read it with inspect_document (compact), make changes with execute_batch using node IDs from the inspect output, then save_document. If a call returns an error, read the "remedy" field and fix the operation. Do not retry the same call unchanged.

Need setup help? See Connect, or open an issue.