> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Anima CLI

> Install anima in an agent runtime — npm for Node/TS agents, signed Linux binary for containers and CI. Every path verifies signatures end-to-end.

# Install the Anima CLI

The `anima` CLI is built for **agents**, not for human click-through installs. That shapes every decision on this page:

* **No macOS or Windows binaries.** Agent workloads run on Linux — in containers, VMs, and CI runners. A developer on a Mac should use the npm package; their agent, when it actually executes, runs on Linux.
* **No Homebrew or Winget.** Those exist to make installs ergonomic for humans; agents read release manifests directly.
* **Sigstore everywhere.** One uniform trust anchor for both install paths, verifiable offline from any pipeline.

## Pick your channel

<Tabs>
  <Tab title="Node / TS agent — npm">
    ```bash theme={null}
    # npm
    npm install -g @anima-labs/cli

    # Bun
    bun install -g @anima-labs/cli

    # pnpm
    pnpm add -g @anima-labs/cli
    ```

    The package is published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), linking the tarball to the exact commit and GitHub Actions workflow that built it.

    Verify the attestation:

    ```bash theme={null}
    npm view @anima-labs/cli --json | jq .dist.attestations
    ```

    Or enforce verification at install time (npm ≥ 9.5):

    ```bash theme={null}
    npm install @anima-labs/cli
    npm audit signatures
    ```

    Use this path when `anima` is a runtime dependency of a Node/TS agent project.
  </Tab>

  <Tab title="Container / CI — curl | sh (Linux x64, arm64)">
    ```bash theme={null}
    curl -fsSL https://get.useanima.sh | sh
    ```

    The installer:

    1. Detects architecture (x64 / arm64) — aborts on non-Linux.
    2. Downloads [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) if not already present (hash-pinned to a known-good build).
    3. Fetches the signed `SHA256SUMS` manifest from the GitHub release.
    4. Verifies the manifest's Sigstore signature against our pinned release-workflow identity.
    5. Downloads the platform binary and checks it against the now-trusted hash.
    6. Installs to `/usr/local/bin` if writable, otherwise `~/.local/bin`.

    If *any* verification step fails, the install aborts — there is no silent fallback. A failed install is visible; a degraded one isn't.

    Pin a specific version (recommended for reproducible container builds):

    ```bash theme={null}
    curl -fsSL https://get.useanima.sh | sh -s -- --version v0.5.0
    ```

    Install into a custom prefix:

    ```bash theme={null}
    curl -fsSL https://get.useanima.sh | sh -s -- --prefix /opt/anima/bin
    ```
  </Tab>
</Tabs>

## Inside a Dockerfile

For a reproducible agent container, pin the version and verify explicitly:

```dockerfile theme={null}
FROM ubuntu:24.04

RUN apt-get update && apt-get install -y curl ca-certificates && rm -rf /var/lib/apt/lists/*

# Pin the version. Bumping this is a deliberate, reviewable change.
ARG ANIMA_VERSION=v0.5.0

RUN curl -fsSL https://get.useanima.sh | sh -s -- --version "$ANIMA_VERSION" \
  && anima --version
```

The installer does the signature verification inline. If the release is ever tampered with or the pinned workflow identity changes, the `RUN` step fails and the image build stops.

## Verify the install

```bash theme={null}
anima --version
anima vault --help
```

## Configuration

Every setting resolves in priority order — a flag wins, then an environment
variable, then the active profile, then your saved defaults:

1. **CLI flag** (e.g. `--org`, `--api-key`, `--api-url`)
2. **Environment variable** (`ANIMA_API_KEY`, `ANIMA_API_URL`, `ANIMA_DEFAULT_ORG`, `ANIMA_DEFAULT_IDENTITY`, `ANIMA_OUTPUT_FORMAT`)
3. **Active profile** (`anima config profile use <name>`)
4. **Saved defaults** (`anima config set <key> <value>` or `anima init`)

This keeps the CLI ergonomic in CI and containers — export your key and default
org once, then drop the flags:

```bash theme={null}
export ANIMA_API_KEY="ak_..."
export ANIMA_DEFAULT_ORG="org_..."
anima security scan   # resolves the org from the environment
```

## Verify a binary manually

Every release asset has a matching Sigstore bundle. To verify end-to-end without trusting the installer (e.g. in an air-gapped pipeline):

```bash theme={null}
VERSION="v0.5.0"
ARCH="$(uname -m | sed 's/x86_64/x64/; s/aarch64/arm64/')"
BIN="anima-linux-${ARCH}"
BASE="https://github.com/anima-labs-ai/cli/releases/download/${VERSION}"

curl -fsSL -O "${BASE}/${BIN}"
curl -fsSL -O "${BASE}/${BIN}.sigstore.bundle"

cosign verify-blob \
  --bundle "${BIN}.sigstore.bundle" \
  --certificate-identity-regexp 'https://github.com/anima-labs-ai/cli/\.github/workflows/release\.yml@refs/tags/v.+' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "${BIN}"
```

A successful verification means:

1. The binary was signed by *our* release workflow, at a release tag — not a different repo's and not a non-tagged build.
2. The signing event is recorded in the public [Rekor transparency log](https://rekor.sigstore.dev) — anyone can audit it.
3. The binary bytes haven't been modified since signing.

## GPG (optional, for distro pipelines)

Releases ship a GPG-signed `SHA256SUMS.asc` when the publisher key is provisioned. This is redundant with Sigstore and exists only for downstream packagers that prefer a traditional PGP trust chain. Verify with:

```bash theme={null}
gpg --verify SHA256SUMS.asc SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
```

Our publisher key fingerprint is published at [useanima.sh/.well-known/gpg-key.asc](https://useanima.sh/.well-known/gpg-key.asc).

## Troubleshooting

**`Unsupported OS`** — You ran the `curl | sh` installer on macOS or Windows. The CLI ships Linux-only binaries; on a developer machine, use `npm install -g @anima-labs/cli` instead.

**Signature verification failed** — Do not proceed. Report at [github.com/anima-labs-ai/cli/issues](https://github.com/anima-labs-ai/cli/issues) and include the full installer output. A failed verification is either a transient CDN issue (retry) or a genuine tampering attempt (we want to hear about it immediately).

**`~/.local/bin not in PATH`** — The installer prints the exact line to add to your shell rc:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

## See also

* [Security](/security) — full signing chain and threat model
* [Quickstart: Vault](/quickstart-vault) — your first `anima vault` command
* [SDKs](/sdks) — Python & TypeScript client libraries