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

# Install the Sparkles CLI

> Install, verify, and update the Sparkles CLI on macOS, Linux, and Windows.

The `sparkles` command runs an installed Claude Code, Codex, or OpenCode agent in a terminal UI and can mirror that session to Sparkles.

## Prerequisites

Install and sign in to at least one supported local agent:

* Claude Code, available as `claude`
* Codex, available as `codex`
* OpenCode, available as `opencode`

Run `sparkles doctor` after installation to see which harnesses are available.

## Installer for macOS and Linux

The HTTPS installer is the recommended channel. It verifies the archive checksum and installs the native binary without requiring Node.js.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://sparkles.dev/install | sh
```

The default destination is `$XDG_BIN_HOME`, or `~/.local/bin` when `XDG_BIN_HOME` is unset. Override the destination or select a version when needed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://sparkles.dev/install | \
  SPARKLES_INSTALL_DIR=/usr/local/bin SPARKLES_VERSION=v1.3.0 sh
```

`SPARKLES_INSTALL_DIR` must be writable by the user who runs the installer. System paths such as `/usr/local/bin` are often root-owned, so either choose a user-owned directory or run the installer as a user with write access to that path.

## Homebrew

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew install sparklesdotdev/tap/sparkles
```

Update an existing installation with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew upgrade sparkles
```

## npm and Windows

The npm package installs a native binary for macOS, Windows, glibc Linux, or musl Linux.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install --global @sparkles-dev/cli
```

Try the CLI without a global install with `npx @sparkles-dev/cli`.

> **macOS signing note:** The installer and Homebrew channels distribute the signed and notarized v1.3.0 macOS binary. The immutable npm v1.3.0 macOS platform package was published before signing was available. macOS users who require a signed binary should use the installer or Homebrew until a newer signed npm version is published.

## Verify the installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles --version
sparkles doctor
```

Version 1.3.0 prints its version and release commit:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles 1.3.0 (ead2e9b06711a50b0920cc379f69f8133bb0bc67)
```

Then authenticate Sparkles for mirrored sessions:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles login
sparkles whoami
```

The local agent keeps its own credentials. Sparkles executes the installed harness and does not read or transport that harness's credential files.

## Update

Use the command that matches the installation channel:

| Channel   | Update command                                   |
| --------- | ------------------------------------------------ |
| Installer | Run the installer again or use `sparkles update` |
| Homebrew  | `brew upgrade sparkles`                          |
| npm       | `npm install --global @sparkles-dev/cli@latest`  |

On Windows, update through npm. On macOS and Linux, `sparkles update` uses the HTTPS installer even when the current executable came from another package manager.

## Start a session

Run Sparkles from a repository:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sparkles
```

Use `sparkles --local-only` when the session must stay on the current computer. Otherwise, Sparkles asks for consent before it mirrors prompts, agent output, tool activity, and diffs to your organization.

Next, learn the [terminal UI controls](/cli/terminal-ui).