# Overview

> Generate and edit images and video, manage assets, and connect MCP clients from your terminal with picx-cli.

`picx-cli` is a command-line client for the PicX API, published on npm. It wraps the same `/v1` REST API this whole reference documents, so anything you can do here you can also script.

| | |
| --- | --- |
| **Install** | `npm i -g picx-cli` |
| **Package** | [`picx-cli`](https://www.npmjs.com/package/picx-cli) on npm, currently 3.0.2 |
| **Auth** | `PICX_API_KEY` env var, same key as the REST API and MCP server |
| **Commands** | 17 — see the [Command Reference](/docs/cli/command-reference) |
| **Output** | Human-readable by default, `--json` for scripts and agents |

> [!NOTE]
> v2.x of `picx-cli` is deprecated — its original host is dead and a module it depended on was removed server-side. Install v3, described below; it's a clean-room rewrite with no shared code or behavior with v2.

## Install & authenticate

```bash
npm i -g picx-cli
export PICX_API_KEY=pxsk_YOUR_KEY
picx whoami
```

No GitHub install, no build step — it's a normal published npm package. Get a key from [API Keys](/docs/developer-tools/api-keys) if you don't have one. `whoami` confirms the key works and reports your account identity — there is no separate `picx auth` command.

## Generate your first image

```bash
picx image "a sunset over mountains, oil painting style"
```

That's the whole quickstart — one command, one credit-charged call, one CDN URL back. For every flag, every command, and the full response shape, see the [Command Reference](/docs/cli/command-reference).

## Connect an AI agent via MCP

`picx mcp install` wires up the [PicX MCP server](/docs/mcp/overview) for Claude Desktop or Cursor in one step, so an agent can call PicX tools directly instead of shelling out to the CLI:

```bash
picx mcp install --client claude
picx mcp doctor
```

`mcp doctor` verifies the endpoint is reachable and the configured API key authenticates before you rely on the connection.

## Where to go next

- [Command Reference](/docs/cli/command-reference) — every command, every flag, every response shape
- [Recipes](/docs/cli/recipes) — batch generation, folder edits, polling loops, CI usage
- [MCP Overview](/docs/mcp/overview) — connect an AI agent directly instead of scripting

## FAQ

### How do I install picx-cli?

`npm i -g picx-cli`. It's published on npm — no GitHub clone or build step needed.

### What happened to v2?

v2.x is deprecated on npm. Its original host is dead and a module it depended on (moodboards) was removed server-side. v3 is an unrelated, clean-room rewrite — install it fresh rather than upgrading in place.

### Can an AI agent use the CLI directly?

Yes, by shelling out to `picx` commands with `--json`, or more directly by using `picx mcp install` to connect the agent to PicX's MCP server instead — see [MCP Overview](/docs/mcp/overview).

### Does the CLI cost anything to use?

The CLI itself is free. `picx image`, `picx image edit`, and `picx video` deduct credits from your account per the live costs shown by `picx models` — read-only commands like `picx whoami`, `picx balance`, and `picx assets list` are free.