Bria Studio

A pretty CLI wizard that sets up the Bria things you'd otherwise wire by hand — Bria models, the MCP server, agent skills, and the SDK — in one place. Think of it as the Bria equivalent of the PostHog setup wizard: run one command, answer a few prompts, done.

npx @bria-ai/studio

Distribution: published to the public npm registry as @bria-ai/studio, so npx @bria-ai/studio works with no extra setup. Or run it from source (see Develop).

Requirements: Node ≥ 18. Setting up a model and the local-stdio MCP flow shell out to uv / uvx, so those need it on your PATH (plus an NVIDIA GPU for GPU-only models such as RMBG 2.0 and FIBO 2).

No install, no clone, no config files to hand-edit. It's a standalone Node CLI, deliberately kept separate from the Python monorepo it lives in — it never touches the uv pipeline tooling.

What it sets up

| Flow | What happens | Source | |------|--------------|--------| | Auth | Log in with your Bria account in the browser (OAuth 2.1 device flow) instead of pasting an API key. Studio shows a code + URL, you approve it, caches a short-lived token under ~/.bria/auth (auto-refreshed), and introspects it to your API key for the other flows. Log out forgets it. | Bria Engine /v2/auth | | Set up a Bria model | Pick a model from your account's catalog (the Engine lists what exists and which licenses you hold), check the license, install the package into an isolated uv venv, download the weights from Bria with progress, and optionally run a quick test (rendered in the terminal). | Bria Engine (/v2/outpost) + CodeArtifact + Bria's weights mirror | | Bria MCP server | Register the Bria MCP with Claude Code, Cursor, or Claude Desktop. Choose transport (hosted HTTP or local stdio) and auth (OAuth or a BRIA_API_KEY token). | HTTP mcp.prod.bria-api.com · stdio bria-mcp | | Bria skills | Pick a target (Claude Code project/global, or Cursor), then multiselect which agent skills to install. | public Bria-AI/bria-skill | | Bria SDK | Pick a client language (Python or TypeScript), then install it with your package manager. | Python bria-client (PyPI) · TypeScript @bria-ai/client (npm) | | For the fun of it | Render a JPEG/PNG you point at — a URL or a local file path — right in the terminal as truecolor half-blocks. | any JPEG/PNG |

Logging in (device auth)

Rather than pasting an API key into every flow, you can log in once. Studio runs the OAuth 2.1 device-authorization grant (RFC 8628) against Bria's authorization server — the Engine host under /v2/auth (api.bria.ai), the same host the token is then presented to:

1. Studio starts a device authorization (as the Engine's fixed public device_auth client — no secret, no per-machine registration).
2. It prints a short code and a verification URL, and opens your browser.
3. You approve the request signed in with your Bria account.
4. Studio receives a short-lived access token + refresh token, cached owner-only under ~/.bria/auth/ and refreshed as it expires.
5. When a flow needs to call the Engine, Studio introspects that token (RFC 7662) to your per-org Bria API key, and sends that as the api_token header — exactly like a pasted key. (The opaque login token isn't a usable API credential on its own; introspection is how it resolves to one.)

The Auth menu logs in, shows status, and logs out. Login is the recommended path, but every flow still accepts a pasted API key, and BRIA_API_TOKEN in the environment is always honored first (CI / scripting). BRIA_CLIENT_BASE_URL points both login and the Engine calls at another environment together.

Organizations. A login resolves to the API key of your current Bria org (the one active when you approved). Switching orgs from the CLI isn't supported yet — the backend has no device-token org-switch endpoint — so switch in the Bria web app and log in again to pick up that org. (Tracked as a follow-up.)

MCP transports & auth

• Streamable HTTP (default) → https://mcp.prod.bria-api.com/mcp. Auth is either OAuth (the client signs you in on first connect — recommended) or a static API token sent as the api_token header.
• Local (stdio) → uvx bria-mcp (the bria-mcp PyPI package). Reads the token from BRIA_API_KEY.

Auth details: https://docs.bria.ai/mcp-authentication

Install locations

Model setups live under one Bria home, so nothing lands in your current directory:

~/.bria/
├── venvs/<model>/     an isolated uv venv per model (never touches your env)
├── models/            model weights, downloaded and verified by the Bria library (~/.bria/models/<model>/<version>/)
├── auth/              your login session (owner-only)
├── entitlements/      the library's cached license verdicts
├── runs/<model>/      the scripts Studio runs in the venv, and the test run's output image
└── cache/             fetched, re-downloadable content

The other flows write where their target expects: the MCP flow updates your client config (~/.cursor/mcp.json, the Claude Desktop config, or Claude Code via its CLI), skills install into ./.claude/skills or ~/.claude/skills (or ~/.cursor/skills), and the SDK flow runs pip/npm install in the current directory.

Override the Bria home root with BRIA_HOME; Studio passes it to the model's Python, so the library reads and writes the same home. Paths are centralized in src/utils/paths.ts.

Setting up a model

The full flow — and the reasoning behind it — is written up in docs/model-setup-flow.md. In short:

1. Bria API key — BRIA_API_TOKEN if set, otherwise Studio asks. Any key of the account works: the account's licenses decide what installs.
2. Pick a model from the Engine's catalog, which lists every model and marks the ones your account holds a license for.
3. License check — the Engine issues the package credential only for a model your account holds a license for. If it holds none, Studio stops with the model's licenses page (https://platform.bria.ai/outpost/licenses?model=…) before it creates anything.
4. Install the package into ~/.bria/venvs/<model> (with the Python the model needs; GPU models get a torch build matching your driver; GPU-only models stop early on a machine with no NVIDIA GPU).
5. Weights — the Bria library, run inside the venv, downloads the weights from Bria and verifies every file, and Studio shows the progress. A second run finds them in place and downloads nothing.
6. Quick test (opt-in, per model) — runs the model once and renders the result in the terminal. Its generation counts as self-hosted usage.

There is no Hugging Face step: every model Studio offers is licensed from Bria and its weights come from Bria.

The model's Python gets three variables from Studio: BRIA_API_TOKEN (the key, never on a command line), BRIA_HOME, and BRIA_CLIENT_BASE_URL (the Engine; default https://engine.prod.bria-api.com). Set BRIA_CLIENT_BASE_URL before starting Studio to point Studio and the library at another environment together.

Nothing in the CLI is labeled commercial; a user only meets the key / license requirement once they're inside this flow.

Telemetry

Bria Studio sends anonymous product-usage events (via PostHog) to help improve it — which flows are used and their outcomes (e.g. a model setup succeeded, or hit no_license / install_failed). It never sends API keys, prompts, file paths, image contents, or logs. A random per-machine id is used, not your identity.

It's disclosed once on first run and is easy to turn off:

• BRIA_STUDIO_TELEMETRY=0 (or DO_NOT_TRACK=1), and it's always off in CI.
• Bria can also disable it remotely (a kill switch) for already-released clients.

Every outbound request carries a bria-studio/<version> (node …; os arch) User-Agent (see src/utils/http.ts).

Develop

Extending this package? Read DEVELOPER.md first — it covers the architecture, conventions, how to add a flow, and the BYOC gotchas.

cd packages/bria-studio
npm install
npm run dev        # run from source (tsx)
npm run typecheck  # tsc --noEmit
npm test           # vitest
npm run build      # bundle to dist/ (tsup)
npm start          # run the built bin

Layout

src/
├── index.ts          # purple banner + looping main menu
├── config.ts         # single source of every endpoint/repo/command
├── ui/               # theme (Bria purple), prompt helpers
├── utils/            # exec, github, paths, bria, outpost, progress, image, torch, http, version, telemetry
└── commands/         # model, mcp, skills, sdk, fun — one flow each

Built with @clack/prompts for the wizard and chalk + gradient-string for the purple styling.

CI & release

• CI — .github/workflows/ci_bria_studio.yml runs typecheck, tests, and build on every PR that touches this package.
• Release — registered with release-please as a node package (tags: bria-studio-v*).
• Publish — .github/workflows/publish_bria_studio.yml triggers on the release tag and publishes @bria-ai/studio to npm via OIDC trusted publishing (tokenless, with provenance) — same pattern as Bria-AI/bria-client. The first release is published manually; the workflow handles the rest.