Annie CLI - Starter Kit

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

Install Annie

Homebrew (recommended)
Arch Linux (AUR)
Manual Download

brew install anyshift-io/tap/annie

yay -S anyshift-annie-bin

Or with paru:

paru -S anyshift-annie-bin

Download the latest release for your platform:

# 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/

Authenticate

Annie ships with production defaults, so no manual configuration is needed. Just log in:

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

Start Asking

Launch the interactive TUI or ask a one-shot question:

# 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:

# 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:

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

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:

> Use the annie cli to determine how many ec2 instances are in <Anyshift Project Name>

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. It teaches the agent when to reach for annie ask versus the remote MCP server, how to chain calls, and what to do when a call fails.

Reference

TUI: resume, slash commands, keyboard shortcuts

Resume a previous conversation. Your last conversation ID is saved when you exit:

# Resume the last conversation
annie --resume

# Resume a specific conversation by ID
annie --conversation <id>

Follow-up questions continue in the same thread with full context from the previous session.Slash commands:

Command	Description
`/help`	Show available commands
`/rca <prompt>`	Run a root-cause analysis instead of a chat
`/report <prompt>`	Ask Annie to format the answer as report blocks
`/save-report <name>`	Save the last report-shaped answer as a reusable definition
`/reports`	List custom report definitions in the active project
`/reports show <instance-id>`	Render a specific report instance as markdown
`/reports run <def-id>`	Trigger a fresh run of a report definition
`/reports history <def-id>`	List past runs of a report definition
`/rcas`	List past RCAs in the active project
`/rcas show <rca-id>`	Render a past RCA’s answer (8-char prefix accepted)
`/rate up\|down`	Rate the last answer with thumbs up or down
`/rate hypothesis <n> 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.

annie ask: all flags and variations

# 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 <id> "what about the database?"

Browse past RCAs

List every RCA in your active project, most recent first:

annie rca list

Render a past RCA’s answer. The first 8 characters of the id are enough:

annie rca get e3025fb6

JSON output is also supported:

annie rca list -o json
annie rca get e3025fb6 -o json

In the TUI, the same flow is /rcas and /rcas show <rca-id>.

Custom reports

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:

annie ask --report "weekly SRE digest"

In the TUI: /report weekly SRE digestSave a report as a reusable definition. After Annie returns a report-shaped answer, persist it so you can re-run the same question later:

annie ask --report --save-as "Weekly SRE Digest" "weekly SRE digest"

In the TUI, run /save-report <name> immediately after a /report answer:

/report weekly SRE digest
/save-report Weekly SRE Digest

Manage report definitions:

# List definitions in the active project
annie report list

# List instances (past runs) of a definition
annie report list --instances <def-id>

# Render a specific instance as markdown
annie report get <instance-id>

# Trigger a fresh run of a definition
annie report generate <def-id>

# Show the status of one instance
annie report status <instance-id>

All id arguments accept an 8-character prefix. The TUI exposes the same operations as /reports, /reports show <id>, /reports run <id>, and /reports history <id>.

Feedback on Annie's answers

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:

# 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:

annie rca get <rca-id> -o json | jq '.hypotheses[].id'
annie feedback hypothesis up <hypothesis-id>

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:

annie ask --prompt-feedback "what changed in production?"

The prompt only fires in interactive terminals, so pipes and scripts are not blocked.

Project management

Annie inherits the active project from the backend. Discover and switch projects from the terminal:

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

Authentication

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

Token-based authentication (CI / headless)

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:

export ANNIE_TOKEN=anys_api_...           # the access-token plaintext
export ANNIE_PROJECT_ID=<project-uuid>    # 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):

annie auth login --token anys_api_...

Project resolution. For each invocation the CLI picks the active project in this order:

--project <name|uuid> flag (one-shot override).
ANNIE_PROJECT_ID env var.
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.
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

- 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: <your-project-uuid>  # 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.

Configuration and privacy

Annie works out of the box with sensible defaults. Override settings via ~/.annie/config.yaml or ANNIE_ prefixed environment variables:

annie config set <key> <value>
annie config get <key>
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

Create Account

Request Demo

See Annie CLI in action

Documentation Index

​Get Started

​Core Usage

​Interactive Chat

​One-Shot Queries

​Pipe Anything

​Root Cause Analyses

​Use from AI Coding Agents

​Reference

​Sign Up

Create Account

Request Demo

Get Started

Core Usage

Interactive Chat

One-Shot Queries

Pipe Anything

Root Cause Analyses

Use from AI Coding Agents

Reference

Sign Up