> ## Documentation Index > Fetch the complete documentation index at: https://docs.anyshift.io/llms.txt > Use this file to discover all available pages before exploring further. # Annie CLI > Ask questions about your infrastructure directly from your terminal. Pipe in logs, explore alerts, and get instant AI-powered analysis without leaving the command line. Annie CLI is a terminal-native AI assistant for infrastructure observability. Ask natural language questions, pipe in kubectl output or logs, and get markdown-rendered answers, all from your terminal. ## Get Started ```bash theme={null} brew install anyshift-io/tap/annie ``` ```bash theme={null} yay -S anyshift-annie-bin ``` Or with `paru`: ```bash theme={null} paru -S anyshift-annie-bin ``` Download the latest release for your platform: ```bash theme={null} # macOS (Apple Silicon) curl -sL https://annie-cli.anyshift.io/releases/latest/annie-darwin-arm64.tar.gz | tar xz mv annie /usr/local/bin/ # macOS (Intel) curl -sL https://annie-cli.anyshift.io/releases/latest/annie-darwin-amd64.tar.gz | tar xz 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/ ``` Annie ships with production defaults, so no manual configuration is needed. Just log in: ```bash theme={null} annie auth login ``` This opens your browser to complete authentication. Your default project is fetched automatically. If you have access to multiple projects, you'll be prompted to select one. Switch later with `annie project switch `. Launch the interactive TUI or ask a one-shot question: ```bash theme={null} # Interactive chat annie # One-shot query annie ask "why is the checkout service slow?" ``` ## Core Usage ### Interactive Chat Launch `annie` with no arguments to enter the full-screen TUI: active project in the banner, animated thinking spinner, scrollable viewport, and markdown-rendered responses. Context is maintained across the session for natural follow-ups. Slash commands autocomplete: start with `/` and press TAB. ### One-Shot Queries For scripting or quick questions, use `annie ask`: ```bash theme={null} # Ask a question directly annie ask "why is checkout slow?" # Add context annie ask "what changed?" --context env=prod --context team=payments # JSON output for scripting annie ask "list services" --output json | jq '.answer' ``` ### Pipe Anything Annie reads piped stdin automatically. Feed it logs, events, or any text for instant analysis: ```bash theme={null} kubectl get events -A | annie ask "anything unusual?" kubectl logs -n prod -l app=backend --tail=200 | annie cat error.log | annie ask "what's the root cause?" ``` When both stdin and stdout are pipes, Annie falls back to one-shot mode for scripting. ### Root Cause Analyses Annie runs a multi-step investigation when you ask for an RCA: hypotheses are generated, refined, and ranked by confidence. Use this when the question is "why is X failing" rather than "what is X". ```bash theme={null} annie ask --rca "why are our database connection pools getting exhausted?" ``` Or in the TUI: `/rca why are our database connection pools getting exhausted?` Each RCA answer ends with hypotheses labeled `[H1]`, `[H2]`, `[H3]` and a confidence score for each. ### Use from AI Coding Agents Annie works as a bridge between AI coding agents and your infrastructure. For example, from inside [Claude Code](https://docs.anthropic.com/en/docs/claude-code): ``` > Use the annie cli to determine how many ec2 instances are in ``` Claude Code runs `annie ask` on your behalf, interprets the response, and incorporates the infrastructure context into your workflow. For Claude Code specifically, install the [Annie Skills plugin](/pages/product/integration/skills). It teaches the agent when to reach for `annie ask` versus the [remote MCP server](/pages/product/integration/remote_mcp), how to chain calls, and what to do when a call fails. ## Reference **Resume a previous conversation.** Your last conversation ID is saved when you exit: ```bash theme={null} # Resume the last conversation annie --resume # Resume a specific conversation by ID annie --conversation ``` Follow-up questions continue in the same thread with full context from the previous session. **Slash commands:** | Command | Description | | ------------------------------- | ---------------------------------------------------------------------------------------- | | `/help` | Show available commands | | `/rca ` | Run a root-cause analysis instead of a chat | | `/report ` | Ask Annie to format the answer as report blocks | | `/save-report ` | Save the last report-shaped answer as a reusable definition | | `/reports` | List custom report definitions in the active project | | `/reports show ` | Render a specific report instance as markdown | | `/reports run ` | Trigger a fresh run of a report definition | | `/reports history ` | List past runs of a report definition | | `/rcas` | List past RCAs in the active project | | `/rcas show ` | Render a past RCA's answer (8-char prefix accepted) | | `/rate up\|down` | Rate the last answer with thumbs up or down | | `/rate hypothesis up\|down` | Rate hypothesis number `n` from the last RCA | | `/copy` | Copy last response to clipboard | | `/mouse` | Toggle mouse tracking (disable for text selection) | | `/project` | Switch active project | | `/share` | Copy conversation URL to clipboard | | `/export [path]` | Export conversation as timestamped markdown file (optionally specify a custom file path) | | `/clear` | Clear screen (keeps session context) | | `/context` | Show project, conversation ID, and piped context info | | `/alerts` | Quick prompt for active alerts | | `/services` | Quick prompt for monitored services | | `/json` | Print last response as JSON | | `/quit` | Exit | **Keyboard shortcuts:** | Key | Action | | -------------- | ------------------------------------ | | `Enter` | Send message | | `Tab` | Accept slash command autocomplete | | `Alt+Enter` | Insert newline (multi-line input) | | `Up/Down` | Browse input history across sessions | | `Ctrl+L` | Clear screen | | `Ctrl+U` | Clear input before cursor | | `Page Up/Down` | Scroll through conversation | | `Mouse wheel` | Scroll viewport | | `Ctrl+C` | Cancel in-progress request, or quit | | `Ctrl+D` | Quit | Input history is persisted across sessions, so you can recall previous questions with the Up arrow. ```bash theme={null} # Verbose mode shows the reasoning chain annie ask "show me active alerts" --verbose # Follow-up mode (interactive REPL after initial answer) annie ask "what's failing?" --follow # Override project for a single query (name or UUID, does not change default) annie ask --project "Production - US East" "list s3 buckets" # Custom timeout (default: 15m) annie ask "list all ec2 instances" --timeout 20m # Resume a previous conversation annie ask --resume "any new alerts since then?" annie ask --conversation "what about the database?" ``` List every RCA in your active project, most recent first: ```bash theme={null} annie rca list ``` Render a past RCA's answer. The first 8 characters of the id are enough: ```bash theme={null} annie rca get e3025fb6 ``` JSON output is also supported: ```bash theme={null} annie rca list -o json annie rca get e3025fb6 -o json ``` In the TUI, the same flow is `/rcas` and `/rcas show `. A report is a structured answer with tables, metrics, and findings instead of prose. Use it for scheduled snapshots like a weekly SRE digest, or any question where the shape of the answer matters more than the narrative. **Generate a report-shaped answer:** ```bash theme={null} annie ask --report "weekly SRE digest" ``` In the TUI: `/report weekly SRE digest` **Save a report as a reusable definition.** After Annie returns a report-shaped answer, persist it so you can re-run the same question later: ```bash theme={null} annie ask --report --save-as "Weekly SRE Digest" "weekly SRE digest" ``` In the TUI, run `/save-report ` immediately after a `/report` answer: ``` /report weekly SRE digest /save-report Weekly SRE Digest ``` **Manage report definitions:** ```bash theme={null} # List definitions in the active project annie report list # List instances (past runs) of a definition annie report list --instances # Render a specific instance as markdown annie report get # Trigger a fresh run of a definition annie report generate # Show the status of one instance annie report status ``` All id arguments accept an 8-character prefix. The TUI exposes the same operations as `/reports`, `/reports show `, `/reports run `, and `/reports history `. Rate any answer Annie gives, and rate individual hypotheses inside an RCA. Ratings flow back into Annie so future investigations take your judgment into account. **Rate the most recent answer:** ```bash theme={null} # After any annie ask run annie feedback up annie feedback down ``` The CLI remembers the last answer in your shell, so no ids are required. **Rate a specific hypothesis from an RCA.** Each rendered RCA labels its hypotheses `[H1]`, `[H2]`, etc. To rate one you need its id, which you can grab from the JSON output: ```bash theme={null} annie rca get -o json | jq '.hypotheses[].id' annie feedback hypothesis up ``` In the TUI, you skip the id lookup entirely. The H-number is enough: ``` /rate up /rate hypothesis 1 up /rate hypothesis 2 down ``` **Prompt for feedback after an answer.** To have the CLI ask for a thumbs up or down inline after each `annie ask`, add `--prompt-feedback`: ```bash theme={null} annie ask --prompt-feedback "what changed in production?" ``` The prompt only fires in interactive terminals, so pipes and scripts are not blocked. Annie inherits the active project from the backend. Discover and switch projects from the terminal: ```bash theme={null} # List all projects (active project marked with *) annie project list # Show current project name and ID annie project current # Switch by name (case-insensitive, partial match) annie project switch "Production - US East" ``` In the interactive TUI, use the `/project` slash command for an interactive project selector. ```bash theme={null} # Browser login (default) annie auth login # Check status annie auth status # Logout annie auth logout ``` Tokens are stored locally in `~/.annie/auth.json` with `0600` permissions and auto-refresh when expiring. An alternative to the browser login flow that unlocks **headless and pipeline usage**: places where opening a browser isn't an option. Mint a token once in the web app and use it either: * in **CI / pipelines** (Argo workflows, GitHub Actions, cron): store it as a secret and pass it via `ANNIE_TOKEN`, no `~/.annie/auth.json` needed, the runner is fully ephemeral. * on a **workstation**: persist it via `annie auth login --token` if you'd rather skip the browser flow on this machine. **Mint a token.** In the Anyshift web app, open **Settings → Access tokens → Create token**. You'll pick an ownership kind and (for shared tokens) a scope. | Ownership | Who can act on it | When to pick | | ------------ | ---------------------- | -------------------------------------------------------------------------------------------- | | **Personal** | only you | local CLI use; the token authenticates *as you* and auto-revokes if your user is deactivated | | **Shared** | any org admin in scope | shared CI / automation; survives the minter leaving the org | Shared tokens are further scoped: * **Project-scoped**: token can only call against the listed project(s). Pick this when a workflow runs against one or a few specific projects. * **Org-scoped**: token can call against any project in the org. Pick this when the project changes per pipeline run and you want a single token to cover everything. The token plaintext is shown **once** at mint time. Copy it immediately to your secret store, it's never displayed again. **Use a token from a CI runner:** ```bash theme={null} export ANNIE_TOKEN=anys_api_... # the access-token plaintext export ANNIE_PROJECT_ID= # only required for multi-project tokens; see Project resolution ``` When `ANNIE_TOKEN` is set, the CLI uses the env-supplied token exclusively: no on-disk `auth.json` is read, and `project_id` in local `config.yaml` is ignored. To save the token on disk instead of passing it via env var (e.g. a long-running developer shell on a build box): ```bash theme={null} annie auth login --token anys_api_... ``` **Project resolution.** For each invocation the CLI picks the active project in this order: 1. `--project ` flag (one-shot override). 2. `ANNIE_PROJECT_ID` env var. 3. Backend auto-resolution via `/project/default`: * **Personal token** → your stored default project. * **Shared, project-scoped, one project** → that project. * **Shared, org-scoped, single-project org** → that project. 4. Otherwise: error `no project selected. Set ANNIE_PROJECT_ID, pass --project, …` For **multi-project shared** and **org-scoped, multi-project org** tokens, step 3 returns nothing, so `ANNIE_PROJECT_ID` is required per invocation. The Settings page surfaces a name → UUID dictionary alongside the tokens table so you can copy the right id into your pipeline config. **Example: Argo Workflow step** ```yaml theme={null} - name: ask-annie container: image: ghcr.io/anyshift-io/annie-cli:latest env: - name: ANNIE_TOKEN valueFrom: secretKeyRef: name: annie key: token - name: ANNIE_PROJECT_ID value: # only required for multi-project tokens command: [sh, -c] args: - | echo "{{workflow.outputs.parameters.failure-report}}" | annie ask "summarize this failure and suggest a fix" ``` **What an access token can call.** Chat, RCA, conversation reads, and project listing/default. Admin operations (rotating cloud credentials, modifying integrations, minting more tokens) require a browser session and are rejected from a token even when the minter is an org admin. **Token lifecycle:** | Action | Effect | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Mint** | Plaintext shown once. Copy it to your secret store immediately. | | **Revoke** | The token is rejected on the next request (`401`). Use to kill a leaked token. | | **Expiry** | Optional at mint time (1–365 days). Expired tokens behave like revoked. | | **User deactivation** | Personal tokens auto-revoke when the minter is deactivated. Shared tokens persist (they belong to the project/org, not the human); revoke them explicitly during SSO deprovisioning if needed. | Annie works out of the box with sensible defaults. Override settings via `~/.annie/config.yaml` or `ANNIE_` prefixed environment variables: ```bash theme={null} annie config set annie config get annie config list ``` | Key | Description | | ------------- | -------------------------------------------------- | | `project_id` | Anyshift project ID | | `show_banner` | Show ASCII art banner on launch (default: `true`) | | `telemetry` | Enable anonymous usage telemetry (default: `true`) | **Privacy:** * Anonymous usage telemetry is on by default and can be disabled with `annie config set telemetry false` or `ANNIE_TELEMETRY=off` * The `NO_COLOR` environment variable is respected for accessibility ## Sign Up Sign up for Anyshift See Annie CLI in action