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

# CLI

> Query your production context from the terminal, scripts, and CI.

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

<iframe width="100%" height="400" src="https://www.youtube-nocookie.com/embed/npsgI5T2A_U?rel=0" title="Anyshift CLI demo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Quickstart

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="Homebrew">
        ```bash theme={null}
        brew install anyshift-io/tap/annie
        ```
      </Tab>

      <Tab title="Arch Linux">
        ```bash theme={null}
        yay -S anyshift-annie-bin
        ```
      </Tab>

      <Tab title="Manual">
        Download the archive 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
        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/
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    annie auth login
    ```

    Your browser opens for authentication and the CLI selects your default project.
  </Step>

  <Step title="Ask">
    ```bash theme={null}
    annie ask "why is checkout slow?"
    ```
  </Step>
</Steps>

## Common workflows

<Tabs>
  <Tab title="Interactive">
    Start a terminal chat with session history and markdown output:

    ```bash theme={null}
    annie
    ```
  </Tab>

  <Tab title="One-shot">
    ```bash theme={null}
    annie ask "what changed in production?"
    annie ask "list services" --output json
    ```
  </Tab>

  <Tab title="Pipe data">
    ```bash theme={null}
    kubectl get events -A | annie ask "anything unusual?"
    kubectl logs -n prod -l app=backend --tail=200 | annie
    ```
  </Tab>

  <Tab title="Investigate">
    Run a root-cause analysis with ranked hypotheses:

    ```bash theme={null}
    annie ask --rca "why are database connections exhausted?"
    ```
  </Tab>

  <Tab title="Query the graph">
    Use deterministic, read-only commands for scripts and automation:

    ```bash theme={null}
    annie graph search checkout
    annie graph blast checkout
    annie graph path checkout checkout-postgres --scope operational
    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.
  </Tab>

  <Tab title="Use with agents">
    Coding agents can call the CLI directly:

    ```text theme={null}
    Use the annie CLI to list the EC2 instances in <project name>.
    ```

    For Claude Code, install the [CLI skills plugin](/pages/product/integration/skills). For Annie investigations inside an agent, use [Annie Remote MCP](/pages/product/integration/remote_mcp). For deterministic Production Graph evidence, use [Graph MCP](/pages/product/integration/graph_mcp) or [Production Intelligence for AI Agents](/pages/product/integration/production_intelligence_agent_plugin).
  </Tab>
</Tabs>

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

```bash theme={null}
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:

```bash theme={null}
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:

```yaml .annie.yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

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

```bash theme={null}
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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion icon="terminal" title="Query options">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion icon="diagram-project" title="Graph commands">
    | Command                                  | Result                                                        |
    | ---------------------------------------- | ------------------------------------------------------------- |
    | `annie graph search <query>`             | Find matching resources                                       |
    | `annie graph show <resource>`            | Inspect one resource                                          |
    | `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, and impact                          |
    | `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 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.

    Discover the query language without authentication:

    ```bash theme={null}
    annie graph query --list
    annie graph query --describe blast_radius
    ```

    See the complete [Graph Query Language reference](/pages/product/integration/graph_query_language).
  </Accordion>

  <Accordion icon="code" title="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`.

    Require a schema-validated answer with:

    ```bash theme={null}
    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 |
  </Accordion>

  <Accordion icon="comments" title="Sessions and TUI">
    ```bash theme={null}
    # Resume the latest session
    annie --resume

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

    Manage persistent project context:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion icon="magnifying-glass" title="Past investigations and reports">
    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion icon="folder-tree" title="Projects">
    ```bash theme={null}
    annie project list
    annie project current
    annie project switch "Production"
    ```

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

  <Accordion icon="key" title="Authentication and CI">
    For local use:

    ```bash theme={null}
    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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion icon="thumbs-up" title="Feedback">
    ```bash theme={null}
    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`.
  </Accordion>

  <Accordion icon="gear" title="Configuration and privacy">
    ```bash theme={null}
    annie config set <key> <value>
    annie config get <key>
    annie config list
    ```

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

    ```bash theme={null}
    annie config set telemetry false
    ```

    The CLI also respects `NO_COLOR`.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Create account" icon="user-plus" href="https://app.anyshift.io/">
    Start using Anyshift
  </Card>

  <Card title="Request a demo" icon="phone" href="https://calendly.com/roxane-fischer/30-zoom-meeting?back=1">
    See the CLI in action
  </Card>
</CardGroup>