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

> ## Agent Instructions
> Flowy is a node-based AI creative platform: you generate images, video, audio, 3D and vector on an infinite Canvas, refine on the Studio timeline, and export or publish from the same project.
> Prefer the Flowy MCP server (https://mcp.tryflowy.ai/mcp) or the REST API at https://apis.tryflowy.ai/v1 for programmatic work. Install with `flowy mcp install` from the @flowy/cli package.
> Credits are workspace-scoped. Generations reserve credits on start and only deduct on success, so failed runs refund automatically.

# CLI

> Sign in to Flowy and wire the hosted MCP into your AI agent from the command line.

`@tryflowy/cli` is the `flowy` command: sign in once, then generate media, browse your workspace, and connect the [Flowy MCP](/api/mcp) to Claude, Cursor, or Codex without hand-editing any config files.

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
npm i -g @tryflowy/cli
```

Requires Node.js 20+.

## Set up

<Steps>
  <Step title="Sign in">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    flowy auth login
    ```

    Opens a browser for a loopback OAuth sign-in ([PKCE](/api/oauth)). No
    password ever touches the CLI. Pass `--no-browser` to print the sign-in
    URL instead (useful over SSH), or `--issuer <url>` to point at a
    non-default authorization server. On success, credentials are written to
    `~/.flowy/credentials.json`.
  </Step>

  <Step title="Connect your agent">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    flowy mcp install --client claude|cursor|codex|all
    ```

    Wires the hosted MCP endpoint into the chosen agent's config, or every
    supported one when you omit `--client` (the default is `all`):

    | Client   | What gets written                                                                                                                                     |
    | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `claude` | Runs `claude mcp add --transport http --scope user flowy <url>` if the `claude` CLI is on `PATH`; otherwise prints the exact command to run yourself. |
    | `cursor` | Merges `flowy` into `~/.cursor/mcp.json` under `mcpServers`.                                                                                          |
    | `codex`  | Merges `flowy` into `~/.codex/config.toml` under `mcp_servers`.                                                                                       |

    For ChatGPT (Developer mode) or any other MCP-capable client, `flowy mcp
            install` also prints the endpoint URL and the raw `mcpServers` JSON block
    to paste into the client's own MCP settings. See [MCP server](/api/mcp)
    for the manual setup.
  </Step>

  <Step title="Restart your agent">
    Restart the agent so it picks up the new MCP server, then ask it to
    *"generate an image with Flowy"*.
  </Step>
</Steps>

<Tip>
  Skip the interactive picker with `flowy mcp install --client claude` (or
  `cursor` / `codex`). `--url <mcpUrl>` overrides the hosted endpoint, mainly
  for local development against `flowy mcp stdio`.
</Tip>

## Commands

<Tabs>
  <Tab title="Auth & MCP">
    | Command             | What it does                                                       |
    | ------------------- | ------------------------------------------------------------------ |
    | `flowy auth login`  | Sign in via browser OAuth (loopback + PKCE).                       |
    | `flowy auth logout` | Delete the stored credentials.                                     |
    | `flowy auth status` | Show whether you're signed in, the token's scopes, and its expiry. |
    | `flowy mcp install` | Wire the hosted MCP into an agent (see above).                     |
    | `flowy mcp stdio`   | Run a local stdio MCP server, for stdio-only clients.              |
  </Tab>

  <Tab title="Account & workspace">
    | Command                                   | What it does                                                                              |
    | ----------------------------------------- | ----------------------------------------------------------------------------------------- |
    | `flowy account status`                    | Email, plan, and available credits.                                                       |
    | `flowy account transactions [--size <n>]` | Recent credit transactions (default 20, max 100).                                         |
    | `flowy workspace list`                    | Every workspace the account can act in.                                                   |
    | `flowy workspace set <workspaceId>`       | Select a workspace for future requests (the workspace context).                           |
    | `flowy workspace status`                  | Show the currently selected workspace.                                                    |
    | `flowy workspace unset`                   | Clear the selection: back to the personal account context.                                |
    | `flowy workspace credits [workspaceId]`   | A workspace's credit balance (defaults to the selected context, then the account wallet). |
  </Tab>

  <Tab title="Content">
    | Command                                                            | What it does                                                                                                                                                                              |
    | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `flowy generate image\|video\|audio\|3d <prompt>`                  | Generate media directly. Flags: `--aspect-ratio`, `--resolution`, `--duration`, `--mode` (audio), `--format` (3d), `--input <ref...>` (repeatable reference), `--wait` (poll until done). |
    | `flowy generate status <generationId>`                             | Check a generation's status and outputs.                                                                                                                                                  |
    | `flowy project list`                                               | List the workspace's canvas projects.                                                                                                                                                     |
    | `flowy node create <projectId> --type <type> --prompt <prompt>`    | Start a generation as a node on a project's canvas.                                                                                                                                       |
    | `flowy brandkit list \| get \| create \| update \| delete \| poll` | Manage brand kits (colors, fonts, logos).                                                                                                                                                 |
    | `flowy render status <workflowId>`                                 | Check a composition render's status.                                                                                                                                                      |
  </Tab>

  <Tab title="Skill & misc">
    | Command               | What it does                                                                                    |
    | --------------------- | ----------------------------------------------------------------------------------------------- |
    | `flowy skill install` | Install the [Flowy skill](/api/skills) via the `skills` CLI (`npx skills add flowy-ai/skills`). |
    | `flowy version`       | Print the CLI version and runtime info.                                                         |
    | `flowy` (bare)        | Print the full command listing with usage and examples.                                         |
  </Tab>
</Tabs>

`flowy account` and `flowy workspace` also accept the `acc` / `ws` aliases; `flowy generate` accepts `gen`.

## Workspace context

Every generation and content command acts in your personal **account
context** by default. `flowy workspace set <id>` switches that context to a
team workspace (persisted in `~/.flowy/settings.json`) so subsequent commands
act in, and bill, that workspace instead `flowy workspace unset` reverts to
the account context.