# QuiverAI CLI

Add QuiverAI creations and SVG files to your React project as components.

This is the command-line tool. To call the QuiverAI API from code, install the TypeScript SDK, [`@quiverai/sdk`](https://www.npmjs.com/package/@quiverai/sdk).

```sh
npx quiverai add https://app.quiver.ai/creations/<creation-id>
```

`add` writes one `.tsx` or `.jsx` file that exports a self-contained React component. It edits no other file.

Requires Node.js 22.12 or later.

## Add a component

```sh
# A creation, by URL or id
npx quiverai add https://app.quiver.ai/creations/<creation-id>
npx quiverai add <creation-id> --name logo

# The newest creation in a chat
npx quiverai add https://app.quiver.ai/chat/<chat-id> --latest

# A public share link (no login)
npx quiverai add https://app.quiver.ai/share/<share-id>

# Any SVG file on the web (no login)
npx quiverai add https://example.com/logo.svg --name logo
```

The CLI prints the file it wrote and the line to import it:

```text
Added FoxLogo to src/components/quiverai/fox-logo.tsx
import { FoxLogo } from "@/components/quiverai/fox-logo";
```

The component takes `width`, `height` and `className` props:

```tsx
<FoxLogo width={32} height={32} />
```

### Where the file goes

The first of these that applies:

1. `--path <dir|file>`.
2. `"quiverai": { "dir": "<path>" }` in your `package.json`.
3. The `components` alias in `components.json` (shadcn projects), in a `quiverai/` folder.
4. `src/components/quiverai/` if `src/` exists.
5. `components/quiverai/`.

The file is `.tsx` when the project uses TypeScript and `.jsx` otherwise. In a monorepo, run the command in the app's folder or pass `--cwd ./apps/web`.

### Component name

Without `--name`, the name comes from the creation's file name, or the SVG URL's file name (`fox-logo.svg` becomes `FoxLogo` in `fox-logo.tsx`). In a terminal, the CLI asks `Component name?` with that suggestion filled in; otherwise, or with `--yes`, it uses the suggestion. `React` is reserved and becomes `ReactIcon`.

### Existing files

The CLI never replaces a file silently. If the file exists with different content, it asks first. Outside a terminal, pass `--overwrite`.

### Options

| Option | Description |
| --- | --- |
| `--name <name>` | Component name, in any case (`fox logo`, `fox-logo`, `FoxLogo`). |
| `--latest` | For a chat link, add the newest creation without asking. |
| `--path <dir\|file>` | Write to this folder or file. |
| `--cwd <dir>` | Project folder. Defaults to the current folder. |
| `-o, --overwrite` | Replace an existing file with different content. |
| `--yes` | Skip prompts: use the suggested name and replace a changed file. |
| `--dry-run` | Run the same steps and show what would be written, without writing. |

## Authentication

Creation and chat links need a QuiverAI account. Share links and SVG URLs do not.

```sh
npx quiverai login    # sign in through your browser
npx quiverai whoami   # shows the signed-in account
npx quiverai logout   # signs out
```

On a machine without a browser, such as over SSH, press `H` at the login prompt. Open the link on any device, approve, then paste the URL your browser lands on.

The CLI stores credentials in your OS keychain when one is available, and otherwise in a file only your user can read, under `quiverai/` in your config folder: `$XDG_CONFIG_HOME` if set, otherwise `%APPDATA%` on Windows and `~/.config` elsewhere. Set `QUIVERAI_TOKEN_STORAGE` to `keyring` or `file` to choose.

## Global options

| Option | Description |
| --- | --- |
| `--app-url [url]` | QuiverAI URL to use. Defaults to `https://app.quiver.ai`. Also `QUIVERAI_APP_URL`. Without a URL, in a terminal, it asks you to pick from your saved logins, production and staging, or to type another URL. |
| `-H, --header "Name: value"` | Send a header with every request to the app URL. Repeatable. |
| `--debug` | Print stack traces for unexpected errors. Also `QUIVERAI_DEBUG=1`. |
| `-h, --help` | Show help. |
| `-v, --version` | Show the version. |

To send the same headers every time, save them per URL in `config.json`, in the same `quiverai/` folder as the credentials:

```json
{
  "headers": {
    "https://app.example.com": { "x-custom-header": "value" }
  }
}
```

A header is sent only to the URL it is listed under. A header value cannot contain a line break.