Annie CLI - Starter Kit

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

Installation

Interactive Chat

Launch annie with no arguments to enter the interactive TUI — a full-screen terminal chat showing the active project name in the banner, an animated thinking spinner, scrollable viewport, and markdown-rendered responses. Conversation context is maintained across the session, so you can ask follow-up questions naturally. Slash commands autocomplete as you type — start with / and press TAB to accept the suggestion.

Resume a Previous Conversation

Your last conversation ID is automatically saved when you exit. Pick up where you left off:

# Resume the last conversation
annie --resume

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

When resumed, follow-up questions continue in the same conversation thread — Annie retains the full context from the previous session.

Slash Commands

Keyboard Shortcuts

Input history is persisted across sessions so you can recall previous questions with the Up arrow.

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

# Verbose mode shows the reasoning chain
annie ask "show me active alerts" --verbose

# JSON output for scripting
annie ask "list services" --output json | jq '.answer'

# 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?"

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”. Start an RCA from the one-shot interface with --rca:

annie ask --rca "why are our database connection pools getting exhausted?"

Or from the interactive TUI:

/rca why are our database connection pools getting exhausted?

Each RCA answer ends with a list of hypotheses labeled [H1], [H2], [H3] and a confidence score for each.

Browse past RCAs

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

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

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 for 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 digest

Save a report as a reusable definition

After Annie returns a report-shaped answer, persist it as a definition 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

You can 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 of them 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

If you want the CLI to 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.

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.

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 will run annie ask on your behalf, interpret the response, and incorporate the infrastructure context into your development workflow — no context-switching required.

Project Management

Annie inherits the active project from the backend. You can discover and switch projects directly 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"

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.

Configuration

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

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

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

Get Started