# CLI

> For the complete documentation index, see [llms.txt](https://inkstudioai.com/developers/llms.txt). Every page has a markdown version: add `.md` to its URL.

Create tattoo designs from your terminal with the inkstudioai npm package.

## Install

You need Node.js 18.17 or later. Run the CLI once with npx, or install it globally:

```sh
npx inkstudioai login
npm i -g inkstudioai
```

The package installs two command names with the same function: `inkstudioai` and `inkstudio`. The package is on npm at [https://www.npmjs.com/package/inkstudioai](https://www.npmjs.com/package/inkstudioai).

## Quick start

```sh
# 1. Sign in. New accounts get one free design.
npx inkstudioai login

# 2. Create a design. The image is saved in the current directory.
npx inkstudioai generate "a fox sleeping inside a crescent moon" --style fine-line

# 3. Look for ideas in the public gallery.
npx inkstudioai gallery dragon
```

## Commands

| Command | What it does |
| --- | --- |
| `inkstudioai login` | Sign in with your browser and save an API key on this computer. Options: `--no-browser`, `--key <key>`, `--with-key`. |
| `inkstudioai generate "<prompt>"` | Create a design and save the image. Alias: `gen`. |
| `inkstudioai styles` | List the style ids for `--style`. |
| `inkstudioai designs` | List the designs saved to your account, newest first. Options: `--limit`, `--page`. |
| `inkstudioai gallery [search]` | Search the public gallery. No login needed. |
| `inkstudioai whoami` | Show your plan, free designs, premium credits, and API use today. Alias: `status`. |
| `inkstudioai pricing` | Show the plans and credit packs. |
| `inkstudioai buy <sku>` | Open Stripe checkout for a plan or credit pack. |
| `inkstudioai open <page>` | Open a page of the website: `account`, `pricing`, or `developers`. |
| `inkstudioai mcp` | Start the MCP server. See [MCP server](https://inkstudioai.com/developers/mcp.md). |
| `inkstudioai logout` | Remove the saved key from this computer. |

Every command has `--help`.

## generate options

| Option | What it does |
| --- | --- |
| `-s, --style <id>` | Style id from `inkstudioai styles`. Default: `minimal`. |
| `-c, --color` | Color ink. Default: black ink. |
| `--skin` | Show the design on skin instead of a white background. |
| `--negative <text>` | Things to leave out of the design. |
| `-o, --out <path>` | File or directory for the image. Default: the current directory. |
| `--force` | Overwrite the `--out` file if it exists. |
| `--no-save` | Do not download the image. Only print its URL. |
| `--open` | Open the image when it is ready. |

The CLI never overwrites a file without `--force`. Without `--out`, the file name comes from the prompt, and the CLI adds `-2`, `-3`, and so on when the name exists.

## Global options

| Option | What it does |
| --- | --- |
| `--json` | Print raw JSON for scripts and agents. |
| `--api-key <key>` | Use this key instead of `INKSTUDIO_API_KEY` or the saved key. |
| `--no-color` | Turn off colors. `NO_COLOR` also works. |
| `-h, --help` | Show help. |
| `-v, --version` | Show the version. |

## JSON output and exit codes

Add `--json` to any command to get the raw API response on stdout. Errors are JSON too, with `error`, `code`, and `hints`.

```sh
inkstudioai generate "a paper crane" --json | jq -r .imageUrl
```

Exit codes: `0` success, `1` error, `2` wrong command or options, `3` design created but the image file not saved. With exit code `3`, the design is in your account, so do not generate it again.

## Configuration

| Setting | Where |
| --- | --- |
| API key | `--api-key`, then `INKSTUDIO_API_KEY`, then the saved key. |
| Saved key | `$XDG_CONFIG_HOME/inkstudioai/config.json`, default `~/.config/inkstudioai/config.json`. On Windows: `%APPDATA%\inkstudioai\config.json`. |
| API URL | `INKSTUDIO_API_URL`, default `https://inkstudioai.com/api/v1`. |
| Do not open a browser | `INKSTUDIO_NO_BROWSER=1` |
| No colors | `NO_COLOR=1` or `--no-color` |