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

# Magnet CLI

> Manage Magnet issues, pages, and sandbox images from the command line. Single native binary — no runtime required.

The Magnet CLI lets you work with your Magnet workspace from the terminal: list and create issues and pages, search, link directories to workspaces, and register custom sandbox images.

## Installation

The CLI ships as a single native binary — no Node.js or other runtime required.

<Tabs>
  <Tab title="GitHub Releases (recommended)">
    Download the binary for your platform from [Releases](https://github.com/toolkit-ai/magnet-cli/releases), extract it, and put `magnet` (or `magnet.exe` on Windows) in your `PATH`:

    ```bash theme={null}
    VERSION="v0.1.6"
    PLATFORM="darwin-arm64"   # or linux-amd64, windows-amd64
    curl -sSL "https://github.com/toolkit-ai/magnet-cli/releases/download/${VERSION}/magnet-cli-${PLATFORM}.tar.gz" | tar xz
    sudo mv magnet /usr/local/bin/
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g @magnet-ai/cli
    ```

    The npm package downloads the matching native binary for your platform at install time.
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
magnet --version
```

## Authentication

There are two ways to authenticate, depending on whether you're acting as yourself or as a workspace:

1. **Log in as a user** (recommended for local development) — [`magnet login`](/cli/login) opens your browser and stores a personal CLI token on your machine.

```bash theme={null}
magnet login
```

2. **Workspace API key** (recommended for CI and scripts) — create an API key in your Magnet workspace settings and set it as an environment variable. When `MAGNET_API_KEY` is set, it takes precedence over a stored login.

```bash theme={null}
export MAGNET_API_KEY="your-uuid-api-key"
```

Check which identity the CLI is using with [`magnet whoami`](/cli/whoami).

## Environment variables

| Variable         | Description                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `MAGNET_API_KEY` | Workspace API key. Takes precedence over a stored `magnet login` session. |
| `MAGNET_API_URL` | Base URL for the Magnet API. Defaults to `https://www.magnet.run`.        |

## Commands

| Command                                      | Description                                      |
| -------------------------------------------- | ------------------------------------------------ |
| [`magnet login`](/cli/login)                 | Log in to Magnet via the browser device flow     |
| [`magnet logout`](/cli/logout)               | Revoke the stored CLI token and remove it        |
| [`magnet whoami`](/cli/whoami)               | Show the user or org the CLI is authenticated as |
| [`magnet link`](/cli/link)                   | Link a directory to a Magnet workspace           |
| [`magnet issues`](/cli/issues)               | List, get, create, or update issues              |
| [`magnet pages`](/cli/pages)                 | List, get, create, or update pages               |
| [`magnet search`](/cli/search)               | Search issues and pages                          |
| [`magnet sandbox-image`](/cli/sandbox-image) | Register custom sandbox images                   |

All commands output JSON, so they compose well with `jq` and scripts.