CLI

aos is the command line for the API. Use it to try a call without writing code, and to receive webhooks on your laptop. The package is @advocate-os/cli; it has no dependencies.

#Install

npm install -g @advocate-os/cli     # Node 18 or newer
# or, without installing:  npx @advocate-os/cli <command>
aos --version

#Log in

aos login asks for the API base and a key, checks them with GET /account, and saves them to ~/.config/advocate-os/config.json (readable by you only). Start with a test key. There is no default host: the base is your Advocate OS address plus /api/v1.

aos login --key aos_test_paste_your_key_here --base https://adv.heliosynctech.com/api/v1

To keep the key out of your shell history, use aos login --key-stdin --base https://adv.heliosynctech.com/api/v1 < keyfile.

These environment variables win over the saved file, which is what you want in CI and for AI agents:

Variable	Meaning
AOS_KEY	The API key.
AOS_API_BASE	The API base, including /api/v1.
AOS_SANDBOX_DATE	yyyy-MM-dd, pins the sandbox clock.
AOS_CONFIG	Another path for the config file.

#Commands

Command	Does
aos login [--key K] [--base URL] [--key-stdin]	Check a key and save it.
aos cases get <cnr> [--fresh]	Read a case (GET /cases/{cnr}). --fresh reads the court now, at the higher price.
aos judgments search <query> [--court C] [--from yyyy-MM-dd] [--to yyyy-MM-dd] [--limit N]	Search judgments.
aos listen --forward-to <url> [--events a,b] [--replay]	Forward events to your local server, signed.
aos trigger <event-type> [--cnr CNR]	Send a test event (POST /sandbox/events).
aos sandbox reset	Clear your test data (POST /sandbox/reset).
aos logs tail [--once]	Show your recent requests as they happen.
aos openapi > spec.json	Save the OpenAPI document.

aos cases get SBXX010000012026
aos judgments search "specific performance" --court sc --from 2023-01-01 --limit 5

Data commands print JSON to stdout. The CLI covers these commands only; for any other endpoint use curl or an SDK.

#Receive webhooks on localhost

Our servers cannot reach your laptop, so a webhook endpoint cannot point there. aos listen closes the gap: it reads your event log every two seconds (GET /events?after=) and posts each new event to your local URL, signed the way a real webhook is.

1. Start your handler, for example on http://localhost:3000/hooks/aos.
2. Run the listener:

aos listen --forward-to http://localhost:3000/hooks/aos --events case.next_date_changed,order.published

3. It prints a signing secret for your handler. Use it with webhooks.verify in place of an endpoint's whsec_… secret.
4. Make something happen:

aos trigger case.next_date_changed --cnr SBXX010000012026

The listener shows case.next_date_changed evt_… -> 200. Add --replay to also send events already in the log. --events accepts a wildcard, such as case.* or order.*. aos trigger takes any event type.

This is for development. In production use a real webhook endpoint, which we push to you and retry.

#Errors

An API error is printed to stderr with its type, code, request_id and doc_url, and the command exits with status 1, so a script can stop on it.