Docs / CLI, MCP & files

Working from a terminal

Everything you build in the browser is also a folder of files, and the command line reads and writes that folder. It is the same authoring path, not a second one: what the browser’s Activate checks, apply checks. Use it for CI, for scripted changes, and when an assistant works in a terminal. If you are new here, start with your first automation in the browser.

The command

The command is a9script. Whoever runs your installation gives you the command and tells you how to start it on your machine.

1 · A token

Mint a token under your name → Account → New token, as shown in Build with Claude Code: Full access to write, bound to one environment, the right to manage credentials off unless the token has to change connections. It expires. People and access says what a token can do and how tokens are managed.

2 · Sign in

a9script login --server https://<your authoring address> --token <your token>
a9script whoami

The commands name no environment: the token is bound to one, and every command acts there. Another environment means another token.

Hand back the edit lock first. A browser window that still holds it stops the command line from writing; apply refuses and names the holder. Release it from the badge in the title bar, or with lock status and lock release. Each command holds the lock as itself, so two commands at once refuse each other; a command that stopped without giving it back is freed by your next lock release.

3 · The loop

a9script entity list
a9script describe <endpoint>
a9script probe FindContact --input '{ "email": "ada@example.com" }'
a9script apply ./my-integration --dry-run
a9script apply ./my-integration
a9script run on-order --input _input.json --debug
a9script history <run>
a9script inspect <run> <seq>

Every command answers JSON under --json. Exit codes: 0 ok, 1 error, 2 validation — a typo’d command or action, a word too many or a flag without its value is 2, refused before anything is sent. --help prints to stdout and exits 0; a person’s next: hints go to stderr, so stdout carries the answer alone. run follows the run through any pause and exits on its outcome — 0 when it succeeded, 1 when it did not; started with --no-wait, or still going when --wait runs out, it exits 0 and the run goes on. Every command, below, lists the words and flags each one takes.

4 · The folder

One JSON file per entity, scripts in .js files beside them. A file names, it never numbers: one entity refers to another by its name — the connection shown as CRM is crm in a file. A credential’s value is never in a file; it is entered in the browser. The folder model is the full description, with every kind.

Good to know

• --debug, --step and probe are sandbox-only; production refuses them before anything runs.
• Write probes are off for tokens until a tenant admin switches them on for the sandbox.
• apply never deletes; remove an entity in the browser.
• An assistant in a terminal follows the authoring loop with these commands.
• authoring-pack prints the whole model, the function list and the common mistakes, from the installation you are talking to — hand it to an assistant.

Every command

Every command, the words it takes and its flags, from the command line’s own declarations — a9script --help prints the same, and a9script <command> --help that command’s part. A flag’s default is what the command does when the flag is left out.

login

Store a PAT.

a9script login --server <url> [--token <pat>]

• --server <url> — the authoring address the token was minted at; the profile stores it beside the token. Required.
• --token <pat> — the personal access token to store, checked with the server before anything is written. Default: the A9SCRIPT_TOKEN variable.

whoami

Who the stored credential is, and where it is bound.

a9script whoami

setup

Turn a first-run setup token into the first administrator.

a9script setup --server <url> --token <setup-token> --email <email> --name <name> --password <password>

• --server <url> — the authoring address of the installation being set up. Required.
• --token <setup-token> — the one-time setup token the server prints in its log on its first start. Required.
• --email <email> — the first administrator’s email address, to sign in with. Required.
• --name <name> — the first administrator’s name. Required.
• --password <password> — the first administrator’s password. Required.

filestore

Read and create the environment’s file stores.

a9script filestore list|create [<name>] [--config <json>]

• list, create — what to do with the environment’s file stores.
• <name> — the store’s name, for create.
• --config <json> — the new store’s configuration as inline JSON: its write policy and, for a runtime store, its bounds; for create. Default: {"writePolicy":"runtime"}.

files

Move files in and out of a file store.

a9script files list|upload|upload-folder|download|delete <store> [<path>] [--from <local>] [--out <local>] [--type <mime>]

• list, upload, upload-folder, download, delete — what to do with the files in a store.
• <store> — which file store.
• <path> — the file’s path in that store — or, for upload and upload-folder without --from, the file or folder on this machine.
• --from <local> — the file on this machine upload sends, or the folder upload-folder sends. Default: the <path> word, which upload stores under its base name.
• --out <local> — where on this machine download writes the file. Default: the file’s own bytes, on stdout.
• --type <mime> — the media type upload stores the file as; the default claims none, so the file is served as its path says, and upload-folder refuses it, each file’s type coming from its path. Default: application/octet-stream.

entity

Read and write the environment’s entities, one at a time.

a9script entity list|get|create|update|delete [<kind>] [<name>] [--file <path>] [--data <json>]

• list, get, create, update, delete — what to do with the environment’s entities.
• <kind> — the entity’s kind, for get and delete.
• <name> — the entity’s name, for get and delete.
• --file <path> — the entity as a JSON document, for create and update; this or --data, never both; a codeFile or bodyFile in it is read from beside it.
• --data <json> — the entity as inline JSON, for create and update; this or --file, never both.

apply

Upsert a .json file, or a folder of them, by name.

a9script apply <path> [--atomic] [--dry-run]

• <path> — a .json file, or a folder of them.
• --atomic — the whole folder as one change: all of it lands or none of it; not with --dry-run.
• --dry-run — check the folder (every entity, and every script’s code compiled), then write nothing; not with --atomic.

describe

What a door takes: its URL, the credential it asks for, the networks it answers, what runs behind it and the shapes it declares.

a9script describe <endpoint>

• <endpoint> — the endpoint’s name.

lock

Read the environment’s edit lock, or give it back.

a9script lock status|release

• status, release — read the environment’s edit lock, or give it back.

run

Follows the run through any pause and exits on the RUN’s outcome.

a9script run <script> [--input <path>] [--debug] [--step] [--wait <duration>] [--no-wait]

• <script> — the main script to run, by name.
• --input <path> — the JSON the script reads as input.event.body.
• --debug — sandbox only: keep every outbound call’s request and response, for history and inspect.
• --step — sandbox only: pause after every outbound call until continue, each call kept as --debug keeps it; not with --wait or --no-wait.
• --wait <duration> — how long to follow the run through its pauses: 30s, 5m, 2h, or a bare number of seconds, at most 24h; when it runs out the run goes on, and the answer is still a success, with waitExpired. Default: 10m.
• --no-wait — start the run and answer at once, without following it; the run goes on.

probe

Fire ONE configured call and read the whole exchange (sandbox only).

a9script probe <function> [--input <json>] [--acknowledge-write]

• <function> — the config function to fire once, by name.
• --input <json> — the call’s arguments, as inline JSON.
• --acknowledge-write — fire a call the platform classifies as a write, where the environment’s policy lets a token fire one.

runs

The environment’s runs, newest first, or one run whole: its lines and its outcome.

a9script runs [<run>] [--script <name>] [--status <status>] [--before <instant|run>] [--limit <n>]

• <run> — one run’s id, to read it whole.
• --script <name> — only the runs of this script.
• --status <status> — only the runs whose status is this one: running, succeeded, failed, stopped.
• --before <instant|run> — the runs before this run (its id, the cursor a full page names) or before this instant (ISO 8601, with its timezone).
• --limit <n> — how many runs one page draws. Default: 20.

load

What the environment carries: its status and reasons, its lanes’ depths, rates and times, its partners.

a9script load [--window <window>]

• --window <window> — the window the lanes’ rates and the partners are read over: 5m, 15m, 60m. Default: 15m.

sessions

The environment’s paused stepped runs.

a9script sessions

position

Where a stepped run stands: the parked call, the statement, the variables in scope.

a9script position <run>

• <run> — the paused run’s id.

continue

One more external call.

a9script continue <run> [--to-end]

• <run> — the paused run’s id.
• --to-end — stop stepping: the run finishes as an ordinary debug run.

abort

Stop a paused stepped run; nothing further is sent.

a9script abort <run>

• <run> — the paused run’s id.

stop

Stop a running run: what it already sent stays sent, nothing further is.

a9script stop <run>

• <run> — the running run’s id.

history

A debug run’s calls: names, status, verdict.

a9script history <run>

• <run> — the debug run’s id.

inspect

One call whole: request, attempts, bodies.

a9script inspect <run> <seq>

• <run> — the debug run’s id.
• <seq> — which call, by its sequence number.

authoring-pack

How to write a script, for humans and agents.

a9script authoring-pack [--part <name>]

• --part <name> — one part of the pack, by its name; the part a bare call answers names every other. Default: model.

On every command

• --help — print the words and flags of the command named, or of every command when none is.
• --json — answer in JSON on stdout: the command’s own document, or the error with its code and the issues.