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.

Installation

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 — no manual configuration needed. Just log in:

annie auth login

This opens your browser to complete authentication. Your default project is fetched automatically from the backend. If you have access to multiple projects, you’ll be prompted to select one.To switch projects later, use 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?"

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

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.

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:

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

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

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 be asked to 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. If you’d rather save the token on disk than pass it via env var (e.g. a long-running developer shell on a build box), use:

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

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

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

Get Started

Create Account

Request Demo

See Annie CLI in action

Get Started

Product

Privacy & Security

Documentation Index

​Installation

​Interactive Chat

​Resume a Previous Conversation

​Slash Commands

​Keyboard Shortcuts

​One-Shot Queries

​Root Cause Analyses

​Browse past RCAs

​Custom Reports

​Generate a report-shaped answer

​Save a report as a reusable definition

​Manage report definitions

​Feedback on Annie’s Answers

​Rate the most recent answer

​Rate a specific hypothesis from an RCA

​Prompt for feedback after an answer

​Pipe Anything

​Use from AI Coding Agents

​Project Management

​Authentication

​Token-based authentication

​Mint a token

​Use a token from a CI runner

​Project resolution

​Example — Argo Workflow step

​What an access token can call

​Token lifecycle

​Configuration

​Privacy

​Get Started

Create Account

Request Demo

Installation

Interactive Chat

Resume a Previous Conversation

Slash Commands

Keyboard Shortcuts

One-Shot Queries

Root Cause Analyses

Browse past RCAs

Custom Reports

Generate a report-shaped answer

Save a report as a reusable definition

Manage report definitions

Feedback on Annie’s Answers

Rate the most recent answer

Rate a specific hypothesis from an RCA

Prompt for feedback after an answer

Pipe Anything

Use from AI Coding Agents

Project Management

Authentication

Token-based authentication

Mint a token

Use a token from a CI runner

Project resolution

Example — Argo Workflow step

What an access token can call

Token lifecycle

Configuration

Privacy

Get Started