CLI - Anyshift Docs

Ask questions, pipe in logs, or run production investigations without leaving the terminal.

Quickstart

Install

Homebrew
Arch Linux
Manual

brew install anyshift-io/tap/annie

yay -S anyshift-annie-bin

Download the archive for your platform:

# macOS, Apple Silicon
curl -sL https://annie-cli.anyshift.io/releases/latest/annie-darwin-arm64.tar.gz | tar xz
sudo mv annie /usr/local/bin/

# macOS, Intel
curl -sL https://annie-cli.anyshift.io/releases/latest/annie-darwin-amd64.tar.gz | tar xz
sudo mv annie /usr/local/bin/

# Linux, amd64
curl -sL https://annie-cli.anyshift.io/releases/latest/annie-linux-amd64.tar.gz | tar xz
sudo mv annie /usr/local/bin/

# Linux, arm64
curl -sL https://annie-cli.anyshift.io/releases/latest/annie-linux-arm64.tar.gz | tar xz
sudo mv annie /usr/local/bin/

Authenticate

annie auth login

Your browser opens for authentication and the CLI selects your default project.

Ask

annie ask "why is checkout slow?"

Common workflows

Start a terminal chat with session history and markdown output:

annie

annie ask "what changed in production?"
annie ask "list services" --output json

kubectl get events -A | annie ask "anything unusual?"
kubectl logs -n prod -l app=backend --tail=200 | annie

Run a root-cause analysis with ranked hypotheses:

annie ask --rca "why are database connections exhausted?"

Use deterministic, read-only commands for scripts and automation:

annie graph search checkout
annie graph blast checkout
annie graph path checkout checkout-postgres --scope operational
annie graph alerts --provider pagerduty --status firing
annie graph incidents --provider pagerduty --status active
annie graph incidents --provider pagerduty --responder "Jane Doe"
annie graph oncall --at now
annie graph oncall --person "Jane Doe" --at now
annie graph triage checkout --since 2h
annie graph query 'SELECT * FROM incident_context WHERE target = checkout AND since = 30d LIMIT 10'
annie graph query 'SELECT * FROM connections WHERE resource = checkout'

Use annie graph for repeatable lookups. Use annie ask when you want an explanation or recommendation.

Coding agents can call the CLI directly:

Use the annie CLI to list the EC2 instances in <project name>.

For Claude Code, install the CLI skills plugin. For Annie investigations inside an agent, use Annie Remote MCP. For deterministic Production Graph evidence, use Graph MCP or the Plugin.

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:

annie update check
annie update check --output json

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:

annie config set update_check false

# Or for one process
ANNIE_UPDATE_CHECK=off annie

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:

annie graph cloud-events --provider gcp --scope gcp/checkout-prod --since 24h
annie graph cloud-events --provider gcp --operation operation-123 --diff
annie graph cloud-resources --type COMPUTE_INSTANCES --max-age 24h

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:

annie graph cloud-events --provider gcp --operation operation-123 --output json \
  | jq '.data.cloudEvents.items[] | {type, evidence, correlation}'

annie graph cloud-resources --provenance unknown --freshness unknown --output json \
  | jq '.data.cloudResources.items[] | {id, provenance, freshness}'

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.yaml

version: 1
project: production
context:
  service: checkout
  environment: production
files:
  - runbooks/checkout.md

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:

annie context show
annie context set team=payments region=us-east-1
annie context add-file runbooks/on-call.md
annie context preview

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:

annie ask "what changed?" \
  --project production \
  --context service=checkout \
  --file runbooks/checkout.md

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:

service-risk.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["risk"],
  "properties": {
    "risk": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  },
  "additionalProperties": false
}

annie ask "assess the deployment risk for checkout" \
  --schema ./service-risk.schema.json \
  --output json | jq -r '.answer.content.risk'

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:

# Find and inspect a conversation
annie conversation list
annie conversation show <id>

# Restore the transcript and continue in the TUI
annie conversation resume <id>

# Continue with a one-shot question
annie ask --conversation <id> "what changed since then?"

# Export the transcript
annie conversation export <id> --output markdown

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.

Reference

Query options

# Include extra context
annie ask "what changed?" --context env=prod --context team=payments

# Attach an explicit repository file
annie ask "check this runbook" --file runbooks/checkout.md

# Select a project for one query
annie ask --project "Production" "list S3 buckets"

# Continue interactively after the answer
annie ask "what is failing?" --follow

# Machine-readable output
annie ask "list services" --output json

# Custom timeout
annie ask "list all EC2 instances" --timeout 20m

Graph commands

Command	Result
`annie graph search <query>`	Find matching resources
`annie graph show <stable-id>`	Inspect one exact current resource and its direct relationships
`annie graph deps <resource>`	Show direct dependencies
`annie graph path <from> <to>`	Find an infrastructure or operational path
`annie graph blast <resource>`	Calculate transitive impact
`annie graph tree <service>`	Expand downstream dependencies
`annie graph diagram <service>`	Generate Mermaid topology
`annie graph timeline <resource>`	Show changes and incident propagation
`annie graph triage <resource>`	Combine symptoms, causes, impact, and optional stored `incident_context` hops
`annie graph posture [resource]`	Find reliability and security gaps
`annie graph check [resource]`	Enforce posture in CI
`annie graph top`	Rank current hotspots
`annie graph explore`	Browse the graph interactively
`annie graph exposure [resource]`	Trace public-edge exposure paths, controls, and origin reachability
`annie graph cloud-events [resource]`	Inspect AWS, Azure, or GCP change evidence
`annie graph cloud-resources [resource]`	Inspect cloud inventory, freshness, lifecycle, and provenance
`annie graph query <statement>`	Run a validated Graph API query

All non-interactive graph commands support --project <name|uuid> and --output text|json. Run annie graph <command> --help for command-specific flags.graph brief and resource-scoped graph check resolve the resource before querying posture. When a name exists in two clusters, qualify the brief or use a stable ID:

annie graph brief checkout --type K8S_DEPLOYMENT --namespace apps --cluster staging
annie graph brief checkout --type K8S_DEPLOYMENT --namespace apps --cluster integration
annie graph check '<stable-id>' --output json

From CLI v0.9.0 with Graph API v0.2.96, each compatible brief/check section uses the selected ID. Brief skips sections whose selector contract cannot preserve that identity: deploy impact, service tree, and alerts for non-service resources. It reports RESOURCE_SCOPE_UNSUPPORTED in workflow.warnings and partial completeness. Unavailable headline.activeAlerts and headline.downstreamServices are null, not zero; text displays unknown. These warnings mean evidence was not queried, not that the resource is missing or healthy.Inspect public exposure for a Cloudflare hostname or a Kubernetes service:

annie graph exposure api.example.com --type CLOUDFLARE_HOSTNAME
annie graph exposure checkout --type K8S_SERVICE --namespace payments
annie graph exposure --id 'cf://accounts/a/zones/z/hostnames/api.example.com'

Each path may include nullable originReachability for internet-facing ALB or NLB security-group evidence versus pinned Cloudflare IP ranges. That field is not DNS proxied / RESOLVES_DIRECTLY_TO, and text output prints it separately from traffic gaps. See Origin reachability.graph triage is deterministic evidence, not AI. It optionally queries incident_context for the resource (target + since + LIMIT). Returned hops are incident, alerts, service, onCall, responders, and history. Empty hops are omitted from findings. History cites reviewed resolution evidence only (confirmed_fix, explicit_reference, or unknown), never temporal-only association. Raw queries use incident_context; PagerDuty setup is on the PagerDuty integration page.graph show accepts a hashedID or anyshiftID returned by graph discovery. It uses the project-scoped Graph API and never guesses from a display name. Resolve a name first, then inspect the selected identity:

annie graph resolve "checkout"
annie graph show '<stable-id>' --output json

The result includes the resource’s safe properties and bounded incoming and outgoing relationships. Text and JSON make relationship truncation explicit. Historical graph show --at reads are not supported until the Graph API has snapshot semantics; use annie graph history for retained change evidence instead.Discover the query language without authentication:

annie graph query --list
annie graph query --describe blast_radius

See the complete Graph Query Language reference.

Automation and exit codes

JSON output uses the annie.cli/v1 envelope. Natural-language answers are returned under .answer.content, while Graph results are returned under .data.From v0.8.60, Graph query validation errors keep the server’s explanation at .error.details.reason, such as an unknown table, the allowed filters, or required time bounds. These errors still return GRAPH_QUERY_INVALID and exit 2. Use the reason to correct the query before retrying. Ambiguous resource errors remain RESOURCE_AMBIGUOUS, with retry choices in .error.details.candidates.Require a schema-validated answer with:

annie ask "assess checkout risk" \
  --schema ./service-risk.schema.json \
  --output json

Code	Meaning
`0`	Success
`1`	Internal CLI error
`2`	Invalid usage or schema
`3`	Authentication or authorization failure
`4`	Backend or network failure
`5`	Timeout or cancellation
`6`	Annie analysis failed
`7`	Requested output schema not satisfied
`8`	A graph check found a gap, risk, or incomplete result

Sessions and TUI

# Resume the latest session
annie --resume

# Resume a specific session
annie --conversation <id>

Manage persistent project context:

annie context show
annie context set service=checkout environment=production
annie context unset environment
annie context add-file runbooks/checkout.md
annie context remove-file runbooks/checkout.md
annie context preview
annie context clear

Essential commands:

Command	Action
`/rca <prompt>`	Run a root-cause analysis
`/report <prompt>`	Generate a structured report
`/project`	Switch project
`/copy`	Copy the latest answer
`/export [path]`	Export the conversation
`/context`	Show resolved context and files
`/context set <key=value\|text>`	Add context to future prompts
`/context add-file <path>`	Attach a file to future prompts
`/context preview`	Preview context sources and file status
`/context clear`	Clear session context and files
`/clear`	Clear the screen
`/quit`	Exit

Use Tab for command completion, Page Up/Down to scroll, and Ctrl+C to cancel.

Past investigations and reports

# Root-cause analyses
annie rca list
annie rca get <rca-id>

# Generate and save a report
annie ask --report --save-as "Weekly SRE Digest" "weekly SRE digest"

# Manage reports
annie report list
annie report list --instances <definition-id>
annie report get <instance-id>
annie report generate <definition-id>

IDs accept an eight-character prefix.

Projects

annie project list
annie project current
annie project switch "Production"

For a single command, use --project <name|uuid>.

Authentication and CI

For local use:

annie auth login
annie auth status
annie auth logout

For CI, create an access token in Settings → Access tokens, store it as a secret, and set:

export ANNIE_TOKEN=anys_api_...
export ANNIE_PROJECT_ID=<project-uuid>
annie ask "summarize the latest deployment"

ANNIE_PROJECT_ID is only required when the token can access multiple projects. Use personal tokens locally and shared tokens for team automation. Token authentication cannot perform administrative operations.

Feedback

annie feedback up
annie feedback down
annie feedback hypothesis up <hypothesis-id>

In the TUI, use /rate up, /rate down, or /rate hypothesis <n> up|down.

Configuration and privacy

annie config set <key> <value>
annie config get <key>
annie config list

Configuration lives in ~/.annie/config.yaml. Disable anonymous telemetry with:

annie config set telemetry false

The CLI also respects NO_COLOR.

Create account

Start using Anyshift

Request a demo

See the CLI in action

​Quickstart

​Common workflows

​Stay up to date

​Investigate GCP changes

​Repository context

​Structured output

​Conversation history

​Reference