Query your production context from the terminal, scripts, and CI.
Ask questions, pipe in logs, or run production investigations without leaving the terminal.
Quickstart
Common workflows
Interactive
One-shot
Pipe data
Investigate
Query the graph
Use with agents
Start a terminal chat with session history and markdown output:
Run a root-cause analysis with ranked hypotheses:
Use deterministic, read-only commands for scripts and automation:
Use annie graph for repeatable lookups. Use annie ask when you want an explanation or recommendation.
Stay up to date
Stable Annie CLI releases tell you when a newer version is available in an interactive terminal. The TUI keeps the available version in its status bar, and successful human-readable commands may show one reminder every 24 hours. Check synchronously whenever you need the current release status:
The JSON form reports the installed version, latest version, update availability, check time, and release URL. Annie does not download or install the update. Passive checks stay silent for JSON output, pipes, redirected streams, CI, help, version, shell completion, development builds, and prereleases. Network failures do not change command output or exit status. Disable passive checks and reminders without disabling the explicit command:
Investigate GCP changes
Use deterministic graph commands when you need retained GCP evidence in a terminal, script, or CI job. List recent events, narrow them to one provider operation, then inspect the affected inventory:
If a fuzzy topology selector matches several equally authoritative resources, Annie exits 2 with
RESOURCE_AMBIGUOUS and lists at most ten stable-ID candidates. JSON keeps the same candidates at
.error.details.candidates. Select one id or anyshiftID and retry; Annie never traverses from an
arbitrary first match.
--operation groups activity by the GCP-native operation identifier. --correlation selects the
broader Anyshift event story. They are separate identifiers. Text output keeps the main evidence
fields; use JSON when automation needs warnings, availability, before and after values, pagination,
or provenance references:
Normal annie graph cloud-events browsing uses bounded page mode. Text output reports the number
shown, whether more results exist, and the next cursor without calculating or claiming an exact
full-window total. Use --exact-stats only when you need the exact total and event-type breakdown;
that opt-in can be slower on large accounts. In page-mode JSON, total is null, byType is empty,
and statistics reports { "mode": "none", "exact": false }.
An unknown status is not success. Unknown provenance does not mean unmanaged, and unknown freshness
does not mean stale. If a response contains nextCursor, pass it back with --cursor to continue
that result page.
Repository context
Add an .annie.yaml file to a repository when you want every question from that workspace to use the same Anyshift project, metadata, and runbooks:
Annie finds the nearest .annie.yaml by walking up from your current directory. Repository settings apply only to that invocation and do not change your global default project.
Use project-scoped personal context when a value should follow you across repositories:
These commands manage your personal context for the selected project. They do not edit the repository’s .annie.yaml.
Invocation flags take precedence over TUI session context, repository context, and personal project context:
Files are included only when you name them. Annie blocks files outside the repository, unsafe symlinks, binary and oversized files, common secret filenames, private keys, token-like content, and Kubernetes Secret manifests. The limits are 32 KiB per file and 96 KiB across one request. Run annie context preview to check file status without printing file contents.
Structured output
Pass a local JSON Schema when a script or CI job needs a predictable object instead of prose:
The CLI validates the schema before sending the request. --schema requires --output json and supports JSON Schema Draft 7 and Draft 2020-12 with an object at the root. Remote schema references are rejected.
Conversation history
Resume a previous investigation with its transcript instead of starting over:
Resume state is scoped to the active project. Annie verifies that the conversation belongs to that project before restoring it. annie conversation delete <id> requires confirmation and may be restricted to administrators.