Fractal Cloud CLI

The fractal CLI is the first-touch experience for Fractal Cloud. Describe what you want to build in natural language, refine across turns, and deploy a real LiveSystem to your initialized cloud environment.

npx @fractal_cloud/cli new "a Node web app with Postgres and a CDN"

Install

Global install for repeat use:

npm install -g @fractal_cloud/cli
fractal --help

One-shot trial without installing:

npx @fractal_cloud/cli new "your idea"

Requires Node.js 20 or later.

Quick start

fractal login                                   # browser-based device flow (RFC 8628)
fractal new "a Node web app with Postgres"      # multi-turn Blueprint conversation
fractal up                                      # pick env + offers, deploy LiveSystem

fractal new opens an interactive 3-region TUI:

• Left — chat with the assistant.
• Right — persistent Blueprint diagram, updated every turn.

On accept, the CLI writes ./fractal.blueprint.json — a human-readable, committable artifact.

fractal up then loads that Blueprint (or any existing one by id), picks an Environment + Resource Group, resolves Components to concrete cloud Offers, submits the LiveSystem, and prints a dashboard link where deployment progress can be followed live.

Commands

fractal login

Authenticates against Fractal Cloud using the OAuth 2.0 Device Authorization Grant (RFC 8628). The CLI prints a short code and opens your browser to the activation page; approve there to complete sign-in.

Access tokens (30 min) and refresh tokens (8 h) are stored in the OS keychain (@napi-rs/keyring) when available, with a ~/.fractal/credentials fallback on Linux (mode 0600). The CLI silently refreshes the access token before it expires.

fractal whoami

Prints the signed-in identity, granted scopes, ACR claims, and remaining token lifetime.

fractal logout

Revokes local credentials. The refresh token is removed from the keychain and the fallback file is deleted.

fractal new [prompt...]

Opens a multi-turn conversation with the assistant. The assistant emits a cloud-agnostic Blueprint matching docs/blueprint-schema.json. After each turn:

• The assistant's explanation renders on the left; the Blueprint diagram renders on the right and refreshes every turn.
• Type /save to persist the latest draft — the CLI prompts for the Resource Group (creates one when none exists) and writes ./fractal.blueprint.json.
• Type /discard to drop the draft and keep refining.
• Type /exit or hit Esc when done. The CLI prints Run \fractal up` to deploy your blueprint.`

Pass an initial prompt as positional arguments to skip the first input:

fractal new "a Python FastAPI service backed by Postgres and Redis"

Flags

| Flag | Effect | |---|---| | --org <orgId> | Persist the Blueprint under an organization's Resource Group instead of your Personal context. GUID required. |

fractal up

End-to-end deploy:

1. Load the Blueprint (local ./fractal.blueprint.json or --fractal-id <id>).
2. Decode the owner from the canonical fractalId (Personal vs Organizational).
3. List your Environments — auto-select when there is one, picker when many, error when none.
4. Pick a Resource Group allowed in the chosen Environment.
5. Resolve offers for every Component across the initialized clouds in the env. Per-component review with arrow-key edit.
6. Pre-deploy summary + confirm prompt.
7. Submit the LiveSystem and print a dashboard URL to follow the deployment.

fractal up                                            # full interactive flow
fractal up --dry-run                                  # stop before submission
fractal up --env staging                              # bypass the env picker
fractal up --env staging --rg default                 # bypass both
fractal up --accept-defaults                          # take the recommended offer for every component
fractal up --fractal-id "Personal/<guid>/wizard/my-app:v0.1.0"   # deploy an existing blueprint
fractal up --org <orgGuid>                            # cross-check: blueprint MUST be Organizational/<orgGuid>

Inside the TUI:

• Top banner — command identity + signed-in user + cwd + shortcut hint.
• Left pane — sequential deploy log: env picked, RG picked, offers resolved, review choices, submission.
• Right pane — Blueprint diagram, continuously updated with picked-offer suffixes.
• Modal popups — env picker, RG picker, offer-edit picker, name prompt, confirm prompt. ↑↓ to move, Enter to select, Esc to cancel, e to edit an offer on the review screen, y/n on confirm.
• Esc / Ctrl-C — quit the TUI. While a popup is open, Esc just closes the popup.

After submission the CLI prints a link such as https://dashboard.fractal.cloud/live-systems/<id> — open it to watch the deployment progress, inspect per-component status, and diagnose failures.

Flags

| Flag | Effect | |---|---| | --org <orgId> | Cross-check that the Blueprint's owner is Organizational/<orgId>. Rejected before any API call when the Blueprint encodes a different owner. | | --env <shortName> | Bypass the env picker. Env must exist and be initialized. | | --rg <shortName> | Bypass the RG picker. RG must be allowed in the chosen env. | | --accept-defaults | Skip per-Component review; take the first offer for every Component. | | --dry-run | Resolve everything, show the summary, exit before submitting. | | --fractal-id <id> | Deploy an existing Blueprint by canonical id (Personal\|Organizational/<ownerGuid>/<rgShortName>/<name>:<version>); skips the local file. |

Requirements

• You are signed in (fractal login).
• You have at least one initialized Environment under the same owner as the Blueprint. Environments in Pending or Failed state are excluded from the picker.
• The Blueprint's fractalId is canonical: Personal|Organizational/<ownerGuid>/<rgShortName>/<name>:<version>.

Layout

Both fractal new and fractal up ship a 3-region neo-blessed TUI:

• Top banner — command identity, signed-in user, working directory, shortcut hint.
• Left pane — conversation log (new) or deploy log + phase modals (up). Scroll with ↑/↓ / PgUp/PgDn / mouse.
• Right pane — persistent Blueprint diagram. new shows the diagram the assistant emits in a fenced ```fractal-diagram block (synth fallback when missing); up synthesizes a compact diagram with per-phase overlays (picked offer).

The layout is the same on every terminal — no single/split toggle. Resize the window and the regions reflow.

Self-update check

On every invocation the CLI:

• Renders a one-line stderr banner when a newer version is in the local cache (~/.fractal/version-check.json, 24h TTL):

  [fractal] Update available: 0.1.0 → 0.2.0. Run `npm i -g @fractal_cloud/cli@latest` to upgrade ...

• Fires a background fetch against the npm registry to refresh the cache for the next run. Non-blocking — never delays the command.

• When FRACTAL_AUTO_UPDATE=1 is set, spawns a detached npm install -g @fractal_cloud/cli@latest after the command exits so the new version is in place for next invocation.

• When FRACTAL_DISABLE_UPDATE_CHECK=1 is set, the entire path (cache read, network fetch, banner, auto-update spawn) is skipped. Useful in CI and locked-down corp networks.

Configuration

The CLI reads configuration from three sources, in priority order:

1. Environment variables.
2. ~/.fractal/config.json (created on first run).
3. Built-in defaults.

Environment variables

| Variable | Default | Purpose | |---|---|---| | FRACTAL_API_URL | https://api.fractal.cloud | Target API host (override for staging). | | FRACTAL_CLIENT_ID | fractal-cli | OAuth client identifier. | | FRACTAL_SCOPE | (empty) | Space-separated scope list. Empty lets the server return the user's full authorized scope set under strict scope policy. | | FRACTAL_FORCE_FILE_CREDS | unset | Set to 1 to bypass @napi-rs/keyring and use the file fallback even on macOS/Windows. Useful in CI. | | FRACTAL_DEBUG_SSE | unset | Set to 1 to dump every Server-Sent Event frame to stderr. Useful when reporting bugs. | | FRACTAL_AUTO_UPDATE | unset | Set to 1 to auto-install the latest version on the next invocation when an update is available. | | FRACTAL_DISABLE_UPDATE_CHECK | unset | Set to 1 to disable the self-update check entirely (no banner, no fetch, no spawn). |

Where files live

| Path | Purpose | |---|---| | ~/.fractal/config.json | Persistent config overrides (apiUrl, clientId, scope). | | ~/.fractal/credentials | Token fallback when @napi-rs/keyring is unavailable (mode 0600). | | ~/.fractal/version-check.json | Last npm-registry self-update check (24h TTL). | | ./fractal.blueprint.json | Committable Blueprint artifact written on accept. | | ./.fractal/session.json | Per-project conversation state (conversationId, last accepted Blueprint, ISO-8601 timestamps). Gitignored. |

Auth model

Authentication uses the RFC 8628 device-flow grant against Fractal Cloud. The CLI never asks the user for a client secret. The issued access token is a JWT carrying the user's principal, granted scopes, and ACRs; the CLI sends it as Authorization: Bearer <jwt> on every protected call.

Strict scope policy is always requested, so a missing scope surfaces as invalid_scope at login time rather than as a confusing 403 mid-session.

Troubleshooting

| Symptom | Action | |---|---| | Not signed in | Run fractal login. | | Your session has expired | Refresh token has expired (8 h after issuance). Run fractal login again. | | invalid_scope at login | Your account is missing a scope the CLI advertises. Ask an admin to grant the listed role, then retry. | | No initialized Environments for Personal/<id> | You have no Environments that have completed initialization. Create + initialize one in the Fractal Cloud dashboard and re-run. | | --org <id> does not match the Blueprint's owner | The Blueprint was authored under a different (or Personal) owner. Drop the flag or pass the correct org GUID. | | Blueprint '<id>' not found | Check the canonical id, confirm you have access, or run fractal new to author one. | | Couldn't submit your LiveSystem | The submission was rejected. The CLI prints the error reason; open the dashboard to inspect environment state. | | assistant stream ended without a result event | Re-run with FRACTAL_DEBUG_SSE=1 fractal new "..." 2> /tmp/sse.log and share /tmp/sse.log. | | Diagram on the right pane is empty during fractal new | The assistant did not emit a fractal-diagram fence on that turn. Refine again; the CLI falls back to a heuristic. | | Want to point at staging | export FRACTAL_API_URL=https://staging.api.fractal.cloud before any command. | | Want a quiet shell (CI, corp net) | export FRACTAL_DISABLE_UPDATE_CHECK=1. | | Slow CLI exit | The bounded post-exit drain on the update check is capped at 1.5s. If you see longer delays, the registry is unreachable — FRACTAL_DISABLE_UPDATE_CHECK=1 skips it entirely. |

Contributing

See CONTRIBUTING.md.

License

Proprietary — © 2026 Fractal Cloud. See LICENSE for terms. The CLI is distributed in compiled form on npm; the source repository is private. Contact [email protected] for commercial licensing.