CLI
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 or the Claude.ai connector; for programmatic use, the REST API.
The framehood CLI is a first-class client for the same toolset you get over MCP and the REST 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
framehoodwith no subcommand.
Both modes share one account, one credit balance, and one set of tools.
Install
brew install framehood/tap/framehoodnpm install -g framehoodgo install github.com/Framehood/framehood-cli@latestgit clone https://github.com/Framehood/framehood-cli
cd framehood-cli && go build -o framehood .Or grab a prebuilt binary from the releases page.
Keep it up to date
framehood upgrade # alias: framehood updateupgrade 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
framehood login # opens your browser (OAuth 2.1 + PKCE, loopback redirect)
framehood logout # remove stored credentials
framehood whoami # email, org role, balance and planlogin 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.
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.
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.
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.
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 for how subscriptions and the shared org credit pool work.
Library
Search your generated assets and manage the trash.
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.
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.
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.
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 and the CLI.
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.
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.
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).
framehoodThe 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.