Skip to content
ASTra
Connect your agent
How it worksDocsGalleryFeaturesConnectGitHub

Quickstart

In about five minutes you will create a document, read its structure, change it, and see ASTra refuse an edit that cannot succeed. You only need a terminal.

Before you start

  • Node.js 22.19.0 or newer. Check with node --version.
  • Nothing else to install: npx downloads ASTra the first time you run it.
  • Optional: LibreOffice, only for PDF export and page images.

1. Create a document

shell
npx -y @attentionform/astra create report.docx --template report

This writes report.docx using the built-in report template. Open it in Word if you like.

2. Read its structure

shell
npx -y @attentionform/astra inspect report.docx --fidelity compact

You get one row per paragraph, with the node's ID, its style and its text:

output
ID       | V | Path | Header | Style    | Text
-------- | - | ---- | ------ | -------- | -----------------------------------------
6C54C7A6 | 1 | Root |        | Title    | Q3 Executive Financial Performance Report
2D12C310 | 1 | Root |        | Subtitle | Strategic Financial Analysis & Growth Projections
3FC95CAC | 1 | Root |        | Heading1 | 1. Executive Summary

The ID is how you point at a node. It does not depend on line numbers or character positions.

3. Change it by ID

Save this as ops.json. It renames the heading and adds a paragraph after it:

ops.json
[{"action":"replace","target":"3FC95CAC","text":"1. Executive Summary (Q4)"},
 {"action":"insert","type":"paragraph","anchor":"3FC95CAC","position":"after","text":"Net revenue grew 24% year over year."}]
shell
npx -y @attentionform/astra batch report.docx ops.json

ASTra prints BATCH OK and the number of operations applied. Both operations apply, or neither does.

4. Check it

shell
npx -y @attentionform/astra validate report.docx
npx -y @attentionform/astra search report.docx "revenue grew"

validate prints VALID (exit code 0) or lists what is wrong (exit code 1). search finds text and prints the IDs of the nodes that contain it, ready to use in the next batch.

5. See a failed edit change nothing

This batch has a valid first operation and a second one that points at a node that does not exist:

shell
echo '[{"action":"replace","target":"3FC95CAC","text":"Changed"},{"action":"replace","target":"DOESNOTEXIST","text":"x"}]' \
  | npx -y @attentionform/astra batch report.docx -

ASTra exits with code 1 and an E_VALIDATION error that ends with Nothing was written. The heading is not "Changed": the whole batch was rolled back and the file is untouched. The message also says how to recover, which is what lets an AI agent fix its own mistake.

Next