# CLI

::: warning Experimental
The CLI is **experimental and may be unstable** — expect rough edges and
breaking changes. For the smoothest experience we recommend the
[Claude Code plugin](/guide/plugin) or the [Claude.ai connector](/guide/claude-ai);
for programmatic use, the [REST API](/reference/api).
:::

The `framehood` CLI is a first-class client for the same toolset you get over
[MCP](/guide/mcp) and the [REST API](/reference/api). It works two ways:

- **One-shot subcommands** — scriptable, automation-friendly commands that run,
  print, and exit (`framehood generate …`, `framehood jobs`, `framehood
  balance`).
- **The interactive studio** — a full-screen terminal app you open by running
  `framehood` with no subcommand.

Both modes share one account, one credit balance, and one set of tools.

## Install

::: code-group

```sh [Homebrew]
brew install framehood/tap/framehood
```

```sh [npm]
npm install -g framehood
```

```sh [go]
go install github.com/Framehood/framehood-cli@latest
```

```sh [source]
git clone https://github.com/Framehood/framehood-cli
cd framehood-cli && go build -o framehood .
```

:::

Or grab a prebuilt binary from the
[releases page](https://github.com/Framehood/framehood-cli/releases/latest).

### Keep it up to date

```sh
framehood upgrade        # alias: framehood update
```

`upgrade` self-replaces the binary with the latest GitHub release. If you
installed through a package manager (Homebrew, npm), it detects that and prints
the right command to run instead of overwriting a managed install.

## Sign in

```sh
framehood login     # opens your browser (OAuth 2.1 + PKCE, loopback redirect)
framehood logout    # remove stored credentials
framehood whoami    # email, org role, balance and plan
```

`login` opens your browser to sign in. The token is stored at
`~/.framehood/credentials.json` (`0600`) and refreshed automatically, so you
rarely need to log in again. `whoami` aggregates your account view — email, org
role, credit balance, and current plan — in one block.

::: tip
The studio can sign you in too: open it signed-out and run `/login` from the
command palette. See [Studio](#studio-interactive).
:::

## Command reference

Every subcommand prints human-readable output and exits non-zero on error, so
they compose cleanly in scripts. Run any command with `--help` for its flags.

### Generate

One-shot generation: submit a prompt, poll until the job finishes, print the
output URL.

```sh
framehood generate "a red fox in the snow"
framehood generate --type audio --voice Rachel "welcome to Framehood"
framehood generate --type video "a drone shot over a coastline"
```

| Flag | Default | Notes |
|------|---------|-------|
| `--type`, `-t` | `image` | `image` · `video` · `audio` |
| `--out`, `-o` | by type | output filename (e.g. `image.jpg`, `video.mp4`, `audio.mp3`) |
| `--action` | by type | override the tool action (`create`, `speak`, `scene`, …) |
| `--tier` | — | image quality tier: `draft` · `fine` · `photo` |
| `--format` | — | size preset, e.g. `landscape_16_9`, `square` |
| `--actor` | — | route through an actor (`act_…`); implies a `scene` for video — *not yet enabled (experimental)* |
| `--voice` | — | voice name for `--type audio` speech |

Defaults per type: image → `image.create`, audio → `audio.speak`, video →
`video.create`. Actor routing (`--actor`, which defaults video to `video.scene`)
is experimental and not yet enabled.

### Jobs

Your generation-history feed, plus per-job cancel.

```sh
framehood jobs                                   # recent jobs (default view)
framehood jobs list --kind flux_schnell --status running,succeeded
framehood jobs cancel <job-id>
```

| Command | Purpose |
|---------|---------|
| `jobs` / `jobs list` | List recent jobs — the generation-history feed |
| `jobs cancel <job-id>` | Cancel a non-terminal job (errors if it already finished) |

List flags: `--kind` (filter by job kind), `--status` (comma-separated, e.g.
`running,succeeded`), `--limit`/`-n` (1–100).

### Billing

Credits, plan, and subscription for your organization. Read views are open to
everyone; subscription changes are owner-only.

```sh
framehood balance                    # top-level shortcut (back-compat)
framehood billing                    # = billing plan
framehood billing balance
framehood billing plan
framehood billing plans
framehood billing transactions -n 20
framehood billing preview <package>
framehood billing change <package>
framehood billing cancel             # cancel at period end
framehood billing cancel --reactivate
```

| Command | Purpose |
|---------|---------|
| `billing balance` | Your current credit balance |
| `billing plan` | Your current plan |
| `billing plans` | The available packages |
| `billing transactions` | Recent credit ledger, newest first (`--limit`/`-n`, 1–50) |
| `billing preview <package>` | Prorated cost of switching to a package (owner only) |
| `billing change <package>` | Switch the subscription, prorated (owner only) |
| `billing cancel` | Cancel at period end; `--reactivate` resumes it (owner only) |

`<package>` is a package id from `billing plans`. See
[Credits & plans](/guide/billing) for how subscriptions and the shared org
credit pool work.

### Library

Search your generated assets and manage the trash.

```sh
framehood library "red fox"              # search by prompt
framehood library --type video -n 50     # filter by media type
framehood library trashed                # list trashed assets
framehood library trash <asset-id>
framehood library restore <asset-id>
```

| Command | Purpose |
|---------|---------|
| `library [query]` | Search your generated assets |
| `library trashed` | List trashed assets |
| `library trash <asset-id>` | Move an asset to trash (recoverable for 10 days) |
| `library restore <asset-id>` | Restore an asset from trash |

List flags: `--type`/`-t` (`image` · `video` · `audio`), `--project` (filter to
a project id), `--limit`/`-n` (default 24).

### Projects

Group your generations into personal or shared projects, and set the active
project so new generations land there automatically.

```sh
framehood project                                 # list your + shared projects
framehood project create "Campaign" --shared --desc "Q3 launch"
framehood project update <project-id> --name "Q4 launch"
framehood project assign <asset-id> <project-id>  # omit id to unassign
framehood project use <project-id>                # set active/default
framehood project current                         # show the active project
framehood project delete <project-id>
```

| Command | Purpose |
|---------|---------|
| `project` | List your personal + shared projects |
| `project create <name>` | Create a project (`--shared`, `--desc`) |
| `project update <project-id>` | Change name / visibility / description (owner only) |
| `project assign <asset-id> [project-id]` | Put an asset in a project; omit the id to unassign |
| `project use [project-id]` | Set the active/default project; omit the id to clear it |
| `project current` | Show the active/default project |
| `project delete <project-id>` | Delete a project (its assets stay in the library) |

Flags: `create` takes `--shared` (org-wide; default is personal) and `--desc`.
`update` takes `--name`, `--visibility` (`personal` · `shared`) and
`--description` — only the fields you pass are changed.

### Team / Org

Your organization: members, spend, and management. Some actions are owner- or
admin-only.

```sh
framehood team                                  # list members
framehood team spend                            # per-member credit spend
framehood team trend --days 30                  # daily org spend (7–90)
framehood team role alice@studio.com admin
framehood team suspend alice@studio.com
framehood team enable alice@studio.com
framehood team invite bob@studio.com
framehood team accept-invite <token>
framehood team remove bob@studio.com
```

| Command | Purpose |
|---------|---------|
| `team` | List organization members |
| `team spend` | Per-member credit spend |
| `team trend` | Daily org credit spend (`--days`, 7–90; default 30) |
| `team role <email> <member\|admin>` | Change a member's role (owner only) |
| `team suspend <email>` | Suspend a member (owner or admin) |
| `team enable <email>` | Re-enable a suspended member (owner or admin) |
| `team invite <email>` | Invite a member by email (owner only) |
| `team accept-invite <token>` | Join an org with an invite token |
| `team remove <email>` | Remove a member (owner only) |

### Files

Manage your storage: list, upload, delete, publish/unpublish, and download.

```sh
framehood files                                     # list (default view)
framehood files --prefix clips/
framehood files upload https://example.com/clip.mp4 clip.mp4
framehood files publish clip.mp4
framehood files unpublish clip.mp4
framehood files download clip.mp4 -o ./clip.mp4
framehood files delete clip.mp4
```

| Command | Purpose |
|---------|---------|
| `files` / `files list` | List your files (`--prefix` to filter by key prefix) |
| `files upload <url> <key>` | Upload a file from a URL |
| `files delete <key>` | Delete a file |
| `files publish <key>` | Make a file public |
| `files unpublish <key>` | Make a published file private again |
| `files download <key>` | Print a usable URL; with `-o <path>` write the file to disk |

`download` resolves a URL for the file. Without `-o` it prints the URL; with
`-o` it fetches the bytes (authenticated for private files) and saves them.

### API keys

Programmatic API keys for the [REST API](/reference/api) and the CLI.

```sh
framehood keys                          # list (prefix + metadata)
framehood keys create --name ci
framehood keys delete <prefix-or-key>
```

| Command | Purpose |
|---------|---------|
| `keys` / `keys list` | List your keys (prefix + metadata) |
| `keys create` | Mint a new key (`--name` is an optional label) |
| `keys delete <prefix-or-key>` | Revoke a key by its prefix or full value |

::: warning
A newly created key's secret is **shown once** and can't be retrieved later.
Copy it immediately.
:::

### Models, skills & workflows

Browse the model catalog, a single model's schema, its prompt guide, and the
multi-step workflows.

```sh
framehood models                        # list available models
framehood models flux_schnell           # one model's full schema
framehood skill flux_schnell            # parameters, tips, prompt guide
framehood workflows                     # list multi-step workflows
framehood workflows video_production    # one workflow's skill
```

| Command | Purpose |
|---------|---------|
| `models [kind]` | List models, or show one model's schema |
| `skill <kind>` | Show a model's skill — parameters, tips, prompt guide |
| `workflows [name]` | List workflows, or show one workflow's skill |

### Config

View or change CLI settings. The output directory is where the studio saves
results.

```sh
framehood config get
framehood config set output-dir ~/Downloads
framehood config set output-dir ""      # clear → current working directory
```

| Command | Purpose |
|---------|---------|
| `config get` | Print the resolved settings (output dir, config dir, MCP base) |
| `config set <key> <value>` | Set a setting (currently `output-dir`) |

`config set output-dir` expands a leading `~`, creates the directory if needed,
and stores the absolute path. Clearing it reverts to the current working
directory.

## Studio (interactive)

Run `framehood` with no subcommand to open the interactive studio — a
full-screen terminal app. It opens even when you're signed out (it shows a
"not signed in" state; `/login` signs you in from inside).

```sh
framehood
```

The compose box at the bottom is your main surface: type a prompt and press
`enter` to generate. The hint line reads
*type a prompt · / for commands · ⇥ to change action*.

### The command palette

Press `/` (from an empty input) to open the **command palette** — a filterable
grid of every action across all tools, plus built-in slash commands. Type to
filter; navigate with `← → ↑ ↓`; press `enter` to run the highlighted command;
`esc` closes it.

You can also type a full command inline. `/image create a red fox` runs the
action with that prompt straight away; `/balance` and `/billing balance` both
resolve to the same action.

Built-in slash commands:

| Command | What it does |
|---------|--------------|
| `/help` | Toggle the full key help |
| `/new` | Clear the current result and start fresh |
| `/open` | Open the selected result in your browser |
| `/copy` | Copy the selected result's URL to the clipboard |
| `/save` | Save the selected result to your output directory |
| `/history` | Jump to the generation-history view |
| `/setdir` | Set the output directory for saved results |
| `/login` · `/logout` · `/whoami` | Manage your session from inside the studio |
| `/upgrade` | Self-update to the latest release |
| `/quit` | Quit the studio |

Beyond these, every tool action (`image create`, `billing
balance`, `files list`, `library list`, `project create`, `org members`,
`api_keys create`, `jobs list`, …) is in the palette (actor actions such as
`video scene` are experimental and not yet enabled). Read-only actions run
immediately; actions that need parameters open a small form (their label ends
with `›`); prompt-only actions close the palette and wait for you to type a
prompt and press `enter`.

### The work-action ring

With the palette closed and the input focused, cycle the **work action** — the
generation action that `enter` submits:

- `⇥` (Tab) — next action
- `⇧⇥` (Shift+Tab) — previous action

This rings through the generation actions (image / video / audio and their
variants) so you can switch what you're creating without opening the palette.

### Input history

In the compose box, recall previously submitted prompts with `↑` / `↓`. Pressing
`↓` past the newest entry restores whatever draft you were typing.

### Results & generation history

While a job runs you see a live status indicator. Finished generations are kept
in a persistent, paginated **history** (stored locally at
`~/.framehood/history.json` — type, prompt, URL, and timestamp only; no tokens).

In the history pane:

| Key | Action |
|-----|--------|
| `↑` / `↓` (or `k` / `j`) | Move the selection |
| `⇞` / `⇟` (PgUp / PgDn) | Newer / older page |
| `o` | Open the selected result in your browser |
| `c` | Copy the result's URL to the clipboard |
| `s` | Save the result to your output directory |
| `u` | Use the result as input for the next action |

### Output directory

Saved results (via `s` or `/save`) go to your configured output directory.
Set it from inside the studio with `/setdir` (or `/setdir ~/Downloads` inline),
or from a shell with `framehood config set output-dir <path>`. Unset, it
defaults to the current working directory.

### Quitting

Press `ctrl+c` **twice** to quit — the first press arms the quit and shows
*press ctrl+c again to quit*; any other key disarms it, so a stray `ctrl+c`
never exits on its own. `/quit` exits immediately.

## Configuration

The CLI defaults to the production Framehood deployment. Override endpoints with
environment variables for local development.

| Env var | Default | Purpose |
|---------|---------|---------|
| `FRAMEHOOD_MCP_BASE` | `https://mcp.framehood.ai` | MCP + OAuth origin |
| `FRAMEHOOD_API_BASE` | same as `FRAMEHOOD_MCP_BASE` | REST `/v1/…` origin |
| `FRAMEHOOD_CONFIG_DIR` | `~/.framehood` | credentials and CLI state directory |

Point `FRAMEHOOD_MCP_BASE` at a local `wrangler dev` worker to develop against
it. Credentials, the local studio history, and CLI settings all live under the
config directory.