CLI Reference
Command reference generated from the Flywheel Usage spec.
Inspect, organize, and operate Flywheel research graphs from the command line.
Command catalog
This reference is generated from flywheel --usage-spec and contains 209 command pages.
Setup Commands
| Command | Summary |
|---|---|
flywheel completion | Generate a shell completion script from the public Flywheel Usage spec |
flywheel completion bash | Generate a bash shell completion script |
flywheel completion fish | Generate a fish shell completion script |
flywheel completion install | Install a generated shell completion script to a user-level location |
flywheel completion nu | Generate a nu shell completion script |
flywheel completion nushell | Generate a nushell shell completion script |
flywheel completion powershell | Generate a powershell shell completion script |
flywheel completion uninstall | Remove Flywheel-managed shell completion files and profile blocks |
flywheel completion zsh | Generate a zsh shell completion script |
flywheel help | Show Flywheel CLI help. |
flywheel setup | Configure host skills or MCP; CLI mode also writes user TOML. |
flywheel uninstall | Remove Flywheel MCP entries and bundled skills from selected hosts |
flywheel version | Print the Flywheel CLI version. |
Auth Commands
| Command | Summary |
|---|---|
flywheel auth:credentials:clear | Remove a locally stored API key for a profile without revoking it. |
flywheel auth:credentials:set | Store an API key in the local credential file for a profile. Reads the key from stdin. |
flywheel auth:login | Bootstrap API key auth through RFC 8628 device authorization flow. |
flywheel auth:status | Report who the current access token signs you in as: authenticated, user_id and email (null when not signed in), auth_enabled (whether sign-in is required) and session_capacity (mode, gate_closed, reason, authenticated_session_admitted, public_surface_mode, web_heartbeat_seconds). Session capacity concerns signed-in web sessions, not compute approval sessions. |
Profile Commands
| Command | Summary |
|---|---|
flywheel profile:list | List built-in and custom profiles from the unified user TOML config. |
flywheel profile:set | Create or update a custom profile in the unified user TOML config (never stores plaintext keys). |
flywheel profile:show | Show a built-in or custom profile without exposing its credential. |
flywheel profile:unset | Delete a custom profile from the unified user TOML config. |
Local Repository
| Command | Summary |
|---|---|
flywheel repo:artifact:attach | Stage an artifact attachment from --metadata-file or the inline --name/--media-type/--notes/--tags flags. |
flywheel repo:artifact:detach | Stage detaching an artifact from its node or edge. |
flywheel repo:artifact:download | Download current-head artifact bytes, fetching and caching a remote-only object when needed; requires --out or --checkout-only. |
flywheel repo:artifact:get | Read one artifact and its references. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:artifact:set-metadata | Stage a replacement for exactly one artifact metadata field from --metadata-file or one inline flag. |
flywheel repo:backup | Create and verify a local repository backup without contacting a service, then record its completion for this checkout. If recording fails, the verified archive remains restorable and the command reports its destination and digest. |
flywheel repo:clone | Clone a hosted projection v4 repository over the network, including boundary-parent and cross-repository tag-scope identities, into a new local directory. |
flywheel repo:commit | Commit the exact current staging digest with its immutable author principal. |
flywheel repo:conflicts:list | List rebase conflicts with each side's changes and values and the resolution choices that work for each, at most 256 per page. |
flywheel repo:conflicts:resolve | Resolve one structured conflict. |
flywheel repo:conflicts:show | Show one rebase conflict: each side's changes and values, the base value when kept, and its usable choices. |
flywheel repo:containment:assign | Stage placing a node inside a container node. |
flywheel repo:containment:get | Read active containment for one child. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:containment:list | List active contained nodes. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:containment:remove | Stage the removal of a containment relation. |
flywheel repo:diff | Compare committed local history or the complete pending staged result without contacting a service. |
flywheel repo:doctor | Report local status (including last_backup), object availability disagreements and interrupted push, pull or purge operations. Confirmed availability repair changes records only and refuses pending work. |
flywheel repo:edge-artifact:list | List edge artifact references. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:edge:add | Stage an edge between distinct descendants of a graph in this repository. |
flywheel repo:edge:get | Read one semantic edge with its endpoints' lifecycle states. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:edge:list | List semantic edges in one graph with each endpoint's lifecycle state. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:edge:remove | Stage the removal of a semantic edge. |
flywheel repo:edge:set-content | Stage new content for a semantic edge. |
flywheel repo:gc | Delete local artifact objects that no commit, staging entry, or backup still references. |
flywheel repo:init | Initialize or adopt the selected local repository at a directory; this command does not choose a hosted default workspace or fork. |
flywheel repo:lineage:add | Stage a parent-child lineage relation. |
flywheel repo:lineage:list | List lineage relations with parent_repository_id and boundary status. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:lineage:remove | Stage the removal of a lineage relation. |
flywheel repo:log | List commits reachable from the local head, newest first. |
flywheel repo:node-artifact:list | List node artifact references. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:node-tag:assign | Stage assigning a tag to a node. |
flywheel repo:node-tag:remove | Stage removing a tag from a node. |
flywheel repo:node:branch | Stage one branched node in the selected local repository and one lineage relation copying the source's title. |
flywheel repo:node:create | Stage a root node in the selected local repository from --title or the full six-field JSON values file; this command never creates or selects another repository. |
flywheel repo:node:get | Read one node and its comparison digests. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:node:list | Discover all local nodes and graph containers, including empty ones. Defaults to committed state; use --staged to inspect pending work. |
flywheel repo:node:merge | Stage one merged node in the selected local repository and one lineage relation from each supplied source, in argument order. |
flywheel repo:node:restore | Stage the restoration of a tombstoned node; retained semantic edges never block it. |
flywheel repo:node:set | Stage one UTF-8 text value for a node field in the selected local repository. |
flywheel repo:node:tombstone | Stage the reversible removal of a node (a later restore undoes it); its history, semantic edges, containment, tags, and attachments stay in the repository. Lineage links must be removed first. |
flywheel repo:pull | Fetch and atomically apply hosted history over the network, preserving boundary references and removing departed nodes while reporting each target_repository_id. |
flywheel repo:purge | Permanently remove one pushed, tombstoned node that nothing references from both the hosted repository and local history (irreversible; requires --confirm). |
flywheel repo:push | Send committed local history to the hosted repository over the network (use --create-remote for the first publication). |
flywheel repo:rebase:abort | Abort one exact rebase, keeping every local commit and pending edit, including ones made while it was open. |
flywheel repo:rebase:continue | Continue one exact rebase: replay every local commit, including ones made while it was open, and keep pending edits that still apply. If later commits change or reopen conflicts, exit 0 with state open means replay is still paused; state continued means replay finished. open_conflict_count counts the conflicts still open; conflict_count counts every recorded conflict, including ones whose earlier choice was kept. |
flywheel repo:recover-departed | Clone the repository that now holds a departed node and replay the selected source checkout's unpublished commits there. If interrupted, check the source checkout with repo:status: if its departure rebase is still paused, delete the destination checkout and run recovery again, and never reuse or push it; if the rebase is finished, keep the destination checkout, which holds the recovered work. |
flywheel repo:restore | Restore a verified backup archive into an empty directory. |
flywheel repo:revert | Create a new local inverse commit for a target's supported reversible changes; node/edge latest-value fields are skipped, while a target containing an edge removal cannot be reverted because its prior content bytes are unavailable. |
flywheel repo:staging:discard | Discard all saved pending operations and associated values from only the selected local repository. Uncommitted work is not recoverable through graph history. Optional repo:backup preserves the batch, but restoring it does not repair invalid staging. No backup is required or created automatically; no export or network transfer occurs. Discard is never implicit in reads, edits, validation, failed commit, pull, push, revert, startup, migration, or upgrade. |
flywheel repo:status | Show local repository status, including the last verified user-requested backup for this checkout (last_backup), interrupted push, pull or purge (interrupted_sync), and an unpublished hosted remote (stranded_remote). A null last_backup means none recorded here, not no remote backups. Push and pull refuse while a rebase is paused or work is staged; interrupted_sync_refused then names why. Before rerunning an interrupted push, pull or purge, continue or abort the paused rebase, then commit or discard the staged work. Rerun the interrupted repo:push with the same --idempotency-key. If the server already accepted that push, the rerun records it: with unchanged local history the server replays the recorded outcome for that key, or nothing is sent if a repo:pull already brought that push in; after later commits or a repo:pull's rebase, the rerun publishes nothing new and reports already_accepted, and the commits still unpublished need a plain repo:push. Otherwise the rerun is an ordinary push. Rerun an interrupted purge with its node_id, --confirm and the same --idempotency-key. For an interrupted pull, run repo:pull again with any key; stranded_remote names the existing repo:push recovery flow. |
flywheel repo:tag:define | Stage a new tag definition under a scope node. |
flywheel repo:tag:list | List tags with each holder's node_id and holder_digest. Defaults to committed local state; use --staged to inspect saved pending work. |
flywheel repo:tag:retire | Stage the retirement of a tag definition. |
flywheel repo:tag:update | Stage a changed tag definition. |
flywheel repo:unpublished:drop | Drop operations from commits not yet pushed and replay the rest as new local commits. Published commits never change. Find operation IDs with repo:log. A never-published repository works offline; otherwise the hosted head must still match the remote-tracking head. Later removals of a dropped lineage add absent from the base are also dropped and reported; other dependent failures refuse without changing local state. |
flywheel ui | Open the local web UI for this folder's repository in your browser. Serves it on 127.0.0.1:8484, or the next free port, until Ctrl-C; reuses one already running. No sign-in needed. |
Hosted Repository
| Command | Summary |
|---|---|
flywheel hosted:artifact:attach | Commit an artifact attachment from --metadata-file or the inline --name/--media-type/--notes/--tags flags. |
flywheel hosted:artifact:detach | Commit detaching an artifact from its node or edge. |
flywheel hosted:artifact:get | Get one artifact's record by id (type, title, note, storage_url, metadata). It returns the record, not the file's bytes: read them separately from storage_url. |
flywheel hosted:artifact:list | List a node's artifact records (type, title, note, storage_url, metadata). By default one page of up to --limit records (default 50, at most 200) from --offset (default 0), with total and has_more; read the next page by raising --offset by --limit. With --all it reads every page itself and prints artifacts and node_revision, as the MCP tool does, without node_id, total, offset, limit or has_more. It returns records, not file bytes. |
flywheel hosted:artifact:set-metadata | Commit a replacement for exactly one artifact metadata field from --metadata-file or one inline flag. |
flywheel hosted:artifact:set-note | Set or clear one artifact's note (markdown allowed). The new note replaces the old one, and an omitted or empty --note clears it. The node's revision is bumped when the note changes; setting the same text again can leave it as is. Needs the node's owner or an admin of it (a repository admin counts); an editor with only write access gets 403. |
flywheel hosted:containment:assign | Commit placing a node inside a container node. |
flywheel hosted:containment:remove | Commit the removal of a containment relation. |
flywheel hosted:edge:add | Commit an edge between distinct descendants of a graph in this repository. |
flywheel hosted:edge:remove | Commit the removal of a semantic edge. |
flywheel hosted:edge:set-content | Commit new content for a semantic edge. |
flywheel hosted:lineage:add | Commit a parent-child lineage relation. Adding a relation that already exists, or one that would make a node its own ancestor (a self-parent included), is refused and nothing is published. The relation belongs to the child's repository. |
flywheel hosted:lineage:list | Read one page of direct visible parents or children. Returns edges (each with cursor and node) and page_info (has_next_page, has_previous_page, start_cursor, end_cursor). Repeat with --after set to page_info.end_cursor while has_next_page is true, keeping the node and --direction unchanged. |
flywheel hosted:lineage:remove | Commit the removal of a lineage relation. Removing a relation that does not exist is refused, not ignored. |
flywheel hosted:node-tag:assign | Commit assigning a tag to a node. One assignment per commit; it never replaces a node's tag list. A one-only tag that another node holds is refused (one-only tag already has a holder): remove it from that node first with hosted:node-tag:remove. |
flywheel hosted:node-tag:remove | Commit removing a tag from a node. One assignment per commit; removing a tag the node does not hold is refused. |
flywheel hosted:node:branch | Create one branched node and one lineage relation from the source. Only the source's title is copied, not its content, summary, tag assignments or artifacts, and the source is unchanged. Without --repository-id the server places it in the source's repository when you hold a repository write role there, otherwise in your fork. A fork node copies the source's sharing when you hold a named Editor or Admin grant on it; otherwise it starts private unless you have added fork members. With --repository-id, commit it in that hosted repository, which must hold the source. |
flywheel hosted:node:create | Create a node from --title or the full six-field JSON values file. Without --repository-id the server places it: under --parent, in the parent's repository when you hold a repository write role there, otherwise in your fork. A fork node copies the parents' sharing when all parents are in one upstream repository and you hold a named Editor or Admin grant on every parent; otherwise it starts private unless you have added fork members. With no --parent, create a root in your default workspace. With --repository-id, commit a root in that hosted repository. |
flywheel hosted:node:get | Read one node by node_id: title, slug_name, content, summary, tags, revision (the expected_revision for writes), visibility, can_write and timestamps. owner_email and author_email are included only for nodes you own, hold a repository role on, or that are shared with you by name. Public or link access alone does not include these emails. --projection chooses the fields; full includes at most 40 artifacts, with artifacts_total and artifacts_truncated indicating more. Parent and child IDs are not listed: use hosted:lineage:list. |
flywheel hosted:node:list | List one page of nodes with optional filters. Returns nodes, total (all matches), page, page_size and has_more; raise --page while has_more is true. Narrow with --owners, --writers, --visibility, --root_only and --repo_url; --projection sets how much of each node comes back. Use graph:get for connections. Searches only your own nodes unless --access_scopes is given; MCP flywheel_list_nodes always searches owned, shared and public. owner_email and author_email are included only for nodes you own, hold a repository role on, or that are shared with you by name. Public or link access alone does not include these emails; the owner column is empty for other people's public nodes. |
flywheel hosted:node:merge | Commit one merged node in this hosted repository and one lineage relation from each supplied source, in argument order. The sources are kept, not deleted or changed. The merged node takes the first nonblank source title (else "Merged node"); its content and summary start empty. |
flywheel hosted:node:restore | Restore one deleted node. Restores title, content and history, but not parent or child edges; add them with hosted:lineage:add. Restores one node: after a cascade delete, restore each ID in the delete result's tombstoned_node_ids. Without --repository-id, the server finds the repository and answers 404 if the ID is unknown or you cannot write to its repository. |
flywheel hosted:node:set | Commit one UTF-8 text value for a node field in this hosted repository. |
flywheel hosted:node:tombstone | Commit the reversible removal of a node (a later restore undoes it); its history, semantic edges, containment, tags, and attachments stay in the repository. Lineage links must be removed first. Afterwards hosted:node:get answers 404. hosted:node:restore works from the node ID alone; only older scripts need the repository ID. |
flywheel hosted:repository:head | Show the published head of a hosted repository. |
flywheel hosted:repository:list | List hosted repositories with optional names, your role, owner, and kind (default workspace, fork, or other). |
flywheel hosted:repository:member:remove | Remove a collaborator from a hosted repository. |
flywheel hosted:repository:member:set | Add a collaborator or change their role. |
flywheel hosted:repository:members | List the collaborators of a hosted repository with their roles (owner or admin only). |
flywheel hosted:repository:retire | Permanently retire a hosted repository (irreversible; the ID can never be reused): all nodes of the repository stop being readable and cannot be restored. Local clones keep working offline but can no longer sync; publishing the graph again needs repo:init in a new directory plus a re-import under a new identity. |
flywheel hosted:repository:transfer | Transfer ownership of a hosted repository to another member; you remain admin. |
flywheel hosted:tag:define | Commit a new tag definition under a scope node. It adds one definition under the scope node and assigns the tag to no node; use hosted:node-tag:assign. |
flywheel hosted:tag:retire | Commit the retirement of a tag definition. The definition is marked retired: nodes stop showing the tag and it cannot be assigned again (tag definition is not active). Existing assignment and history records are kept, not deleted. |
flywheel hosted:tag:update | Commit a changed tag definition. The definition file replaces the whole definition: write every field, not only the ones that change. |
Nodes & Graph Commands
| Command | Summary |
|---|---|
flywheel campaign:snapshot | Resolve campaign root snapshot for a node. |
flywheel campaign:submissions:get | Read one campaign submission record by id, in whatever lifecycle state it is in: accepted, enqueued, forwarding, forwarded, rate_limited, retrying, scored, rejected or failed. Needs read access to the submission's node; unknown id: 404. |
flywheel campaign:submissions:get-by-artifact | Read the campaign submission record made from one artifact. No record for that artifact on that node: 404. |
flywheel campaign:submissions:list | List the campaign submission records of one node, optionally filtered by --state. Returns at most --limit records (default 100, range 1-200) and has no cursor: narrow with --state when more than --limit exist. |
flywheel graph:get | Read one page of the node graph: roots (records of the starting nodes, each with a node_id), nodes_by_id (nodes keyed by node_id), has_more, next_cursor and page_size. Without --node_id, start at roots in your scopes; with it, walk that node and its descendants, not up to its root. --depth limits the walk. Pass next_cursor as --cursor with all other inputs unchanged until has_more is false. Use hosted:lineage:list for direct neighbours. |
flywheel nodes:files | List files attached to a node. |
flywheel nodes:render:ancestry | Follow ONE path from a node toward a root, not every ancestor. At a merge choose the visible parent with the lowest node ID; multi_parent_choices lists node_id, candidate_parent_ids and selected_parent_id. Returns path_node_ids and nodes from the top down to the anchor, anchor_node_id, root_node_id, path_node_count, path_edge_count, parent_selection_strategy, incomplete_parent_links (parents that could not be loaded), cycle_detected, truncated (stopped at --max_depth) and max_depth. root_node_id is where the path stopped, not necessarily a true root when truncated or incomplete_parent_links is set. Use hosted:lineage:list --direction parents for every direct parent. |
flywheel nodes:render:summary | Summarize a node tree deterministically and for free, without a model: node titles and summaries as Markdown. Returns anchor_node_id, root_node_ids, node_count, latest_updated_at, markdown (one line per node; first summary line cut to 220 characters) and nodes (node_id, title, depth, full summary, artifact_count, execution_count, updated_at). Covers the same tree as nodes:render:tree, limited by --max_nodes. Of the five summary commands, nodes:render:summary and export:summary:render-pdf call no model and cost nothing; export:summary, export:summary:stream and export:summary:pdf call an outside language model and charge credits. |
flywheel nodes:render:tree | Lay out the tree around one node for display, starting from its visible ancestor roots and including siblings and other branches. Returns anchor_node_id, root_node_ids, nodes (node_id, title, depth, lane, is_root, outgoing_ids and incoming_ids within the result), lane_count, max_depth and truncated. Entries contain layout and links, not content: use hosted:node:get for content. truncated is true only when --max_nodes leaves out a qualifying node, not when the count equals the limit. CLI projection defaults to full; MCP defaults to topology. |
flywheel nodes:resolve-slug | Resolve a slug to a node ID. |
flywheel nodes:sharing:get | Read who can see or edit a node. Returns owner_user_id, owner_email, is_owner, is_private, effective (your can_view, can_write, can_admin), link and public viewing rules, link_write, users (each with write, admin and repository_role) and updated_at. The same policy also comes as sharing_mode (private, unlisted or public), visibility (also shared when a private node has collaborators) and collaborators (email and/or user_id, role viewer, editor or admin), the fields the MCP tool flywheel_get_node_sharing returns. Only the owner or an admin may read it; others get 403. Use nodes:sharing:set to change it. |
flywheel nodes:sharing:job:get | Read the progress of a whole-graph sharing job. |
flywheel nodes:sharing:job:resume | Resume a stopped or failed whole-graph sharing job. |
flywheel nodes:sharing:job:stop | Stop a whole-graph sharing job after its current step. |
flywheel nodes:sharing:set | Change node visibility, keeping collaborators unless explicitly replaced; owner or admin only. Prints the new policy with the same fields nodes:sharing:get reads. |
flywheel nodes:sharing:set-bulk | Apply one sharing policy to up to 1000 nodes, all or nothing. |
flywheel nodes:sharing:set-graph | Share a whole graph of any size; wait with progress and return final counts by default. |
flywheel nodes:sharing:summaries | Read access summaries for multiple nodes in one batch. |
flywheel nodes:stage:lease:acquire | Take an edit lease on an existing node for the MCP staged-payload workflow. The lease only gates the MCP tool flywheel_commit_node: the CLI has no command that commits a staged payload, and hosted: and repo: edits do not check it. It lasts 45 seconds by default, so refresh it with nodes:stage:lease:heartbeat about every 15 seconds. Refused with 409 when another session holds a live lease or the base revision is stale; once a lease has expired, acquiring again takes a new one. Running it again with the same --stage_session_id extends the lease and moves it to the --base_committed_revision you send, so after another write to the node, re-run it with the node's new revision. Prints lease (with expires_at and heartbeat_interval_seconds) and the current node. |
flywheel nodes:stage:lease:heartbeat | Extend your stage lease before it expires (45 seconds by default; call about every 15 seconds). Prints the refreshed lease. Refused with 409 when the lease expired or was never taken (stage lease missing or expired) or belongs to another session; run nodes:stage:lease:acquire again. |
flywheel nodes:stage:lease:release | Give up your stage lease without committing anything. Releasing a lease that expired or does not exist succeeds (released: true); another session's live lease is refused with 409. |
flywheel remote-artifacts:refresh | Re-fetch a public HTTPS JSON Remote Artifact now: like remote-artifacts:resolve with --force_refresh always on, so it skips the freshness cache. Exception: while another refresh of the same artifact holds the refresh lock (up to --cache_ttl_seconds) and a cached copy exists, it returns that cached copy (remote_status fresh) without fetching. Unchanged rendered content and source settings keep the artifact and the node's revision; a change replaces the artifact and bumps the revision. Needs write access. |
flywheel remote-artifacts:resolve | Fetch a public HTTPS JSON URL and keep its rows as one artifact on the node, identified by --remote_artifact_id. Serves the cached copy while it is fresh (--cache_ttl_seconds) unless --force_refresh is true. When the rendered content or a source setting (--title, --url, --rows_path, --row_id, --cache_ttl_seconds) changed, replaces the node's artifact for that --remote_artifact_id and bumps the node's revision; otherwise neither changes. Needs write access. remote_artifact.remote_status says what happened: fresh, refreshed, stale_error (fetch failed, earlier artifact kept) or error (fetch failed, no earlier artifact for these source settings). |
Artifacts & Files Commands
| Command | Summary |
|---|---|
flywheel files:list | List all your files across nodes. |
Hooks Commands
| Command | Summary |
|---|---|
flywheel hooks:create | Create one hook on an owner node. Creating a hook runs nothing: it is stored, and while enabled it runs later and automatically, as queued runs, when an artifact.finalized (an artifact upload finalized) or node.published (a node made public with submission artifacts) event matches its scope. A workflow is a restricted set of steps (HTTP requests and polling, JSON extraction, artifact load and upsert, adding tags) and can call outside services, using secrets as $\{\{ secrets.NAME \}\}. Needs write access to the owner node. |
flywheel hooks:delete | Delete one hook and its run history (queued, running and finished runs). It cannot be undone. To stop new and queued runs but keep the history, disable it with hooks:set-enabled. Needs write access to the owner node. |
flywheel hooks:list | List the hooks configured on an owner node (scope, workflow, enabled state). Needs read access. |
flywheel hooks:runs:list | List runs of hooks on an owner node, newest first (queued, running, succeeded, failed or canceled; canceled is a queued run whose hook was disabled, with the reason in error_message), optionally for one hook. Runs are queued automatically when a matching event happens (see hooks:create). Returns at most --limit runs (default 100, range 1-200) and has no paging, so it shows recent history only. Needs read access. |
flywheel hooks:secrets:create | Store a named secret on an owner node for its hooks' workflows to use as $\{\{ secrets.NAME \}\}. The value is stored encrypted and no command returns it. Needs write access to the owner node. |
flywheel hooks:secrets:delete | Delete a hook secret. It cannot be undone and the value cannot be recovered; create a new secret to use the name again. Needs write access to the owner node. |
flywheel hooks:secrets:list | List hook secret metadata for an owner node (secret_id, name, version, timestamps). Never returns secret values. Needs write access to the node, not just read access. |
flywheel hooks:secrets:update | Replace a hook secret's value and bump its version. The old value cannot be retrieved afterwards. Needs write access to the owner node. |
flywheel hooks:set-enabled | Enable or disable one hook. A disabled hook is kept but queues no new runs, and a run of it that is still queued when the worker picks it up does not start: it ends as canceled, with an error message that names the hook. Runs already running are not interrupted. Enabling again does not revive a canceled run; the next matching event queues a new one. The run history stays. Needs write access to the owner node. |
flywheel hooks:update | Update one hook; only the flags you pass change (at least one is required). A supplied --workflow_yaml replaces the old workflow entirely, nothing is merged. Enabling or disabling is a separate command: hooks:set-enabled. Needs write access to the owner node. |
Compute & Executions Commands
| Command | Summary |
|---|---|
flywheel compute:acquire | Rent a machine now at the outside provider that owns the offer (Lambda, Modal, Vast.ai, Prime Intellect, Nebius or RunPod). This starts paid usage: it is billed by the second at the offer's hourly price plus any provider margin the server adds, to your Flywheel credits (to the campaign's sponsor for a root grant), until the lease is released or its grant is used up. It needs an active compute_grant_id bound to the approval session (compute-grants:request-approval first). Returns compute with request_state (accepted or completed), lease_id, lease_control_token, lease_status, provider, offer_id, region, hourly price, grant balances and auto_shutdown_at; it carries no SSH key, so poll compute:status until the lease is usable, then call compute:connection. A call with the same --lease_control_token and grant as a pending or active lease reuses that lease instead of provisioning another, as long as its provider, offer and any --region you give match the lease; if they differ the call fails and says what to change or release. --cmd_id is only a label, not a duplicate guard. Release with compute:release when done: the machine and its storage are destroyed. With --wait, wait for usable SSH connection material. |
flywheel compute:budgets | List budget grants visible for a node context. |
flywheel compute:connection | Read SSH connection material for an active managed compute lease once compute:status indicates the lease is usable. Returns compute with lease_id, lease_status, provider, offer_id, region, host, port, user, private_key (the SSH private key: keep it secret), known_hosts and next_retry_after_seconds; host, port and key are empty until the lease is ready. Scoped to --lease_control_token, and only leases you own are connectable. Pass --lease_id or --node_id to pick one when several match. |
flywheel compute:funding | Read what a compute grant allows and has used. Returns compute with compute_grant_id, budget_source, root_compute_budget_id, grant_cents (what the grant allows), spent_cents and remaining_cents. hard_cap_cents, cumulative_spend_cents and budget_remaining_cents repeat grant_cents, spent_cents and remaining_cents under older names: they are the grant's values, not the backing campaign budget's (for those use campaign-budgets:list). Read it before compute:acquire. |
flywheel compute:options | List the compute machines (offers) you could rent for a node, from the providers this server has enabled. Returns compute with detail, returned_options and options; each compact row has provider, offer_id, display_name, gpu_model, gpu_count, price_cents_per_hour, regions, allowed and preferred. Pick a row with allowed true and pass its offer_id as requested_sku to compute-grants:request-approval and compute:acquire. Listing is free: it takes no grant and returns no budget or funding (see compute:funding). |
flywheel compute:release | Destroy one lease's machine now. It waits for the provider's teardown to finish before it answers; compute:release-all, by contrast, only queues teardown. Teardown deletes the machine and its storage (the bundled disk and, on Nebius, the separate boot disk), so anything you did not export first is lost; nothing is snapshotted. Returns the lease after teardown; state and error report unconfirmed teardown. Global --wait does not change that server-side wait: it adds polling of compute:status in the token scope until released or error (404 also counts as released), returned as wait_result. |
flywheel compute:release-all | Queue teardown of every active lease in your --lease_control_token scope and return at once by default; each machine and its storage are then destroyed in the background, nothing snapshotted. --force --yes widens it to all of your active leases. Returns request_state accepted, target_count and target_lease_ids, or, when nothing matched, request_state completed, outcome no_active_lease and target_count 0. Check progress with compute:status. With a token, --wait adds status polling and returns wait_result; it does not make the server teardown synchronous. |
flywheel compute:status | Read managed compute lease status for the current user and --lease_control_token scope. Returns compute with recommended_next_action (acquire_new_lease, wait_for_release, retry_acquire_active_lease, wait_for_active_lease, use_active_lease or release_or_reacquire), active_lease_id and leases. Lease rows include ownership flags so you can distinguish user-owned leases from sponsor-visible campaign leases; only rows with owned_by_current_user and connection_allowed_for_current_user true can be used for connection or reuse. No SSH private key is returned. When checking a grant-backed lease, reuse the same --compute_grant_id passed to compute:acquire. |
flywheel executions:launch | Record a new execution on a node (status running) and bump the node's revision. It records status only: it starts no process and provisions no compute, and --provider is just a label stored on the record. To run work, acquire a machine with compute:acquire (options: compute:options), run it there, then close the record with executions:terminate. Needs the node's owner or an admin. |
flywheel executions:list | List the execution records stored on a node (running, completed, failed or canceled). They are stored records, not live process state: they change only when executions:launch or executions:terminate runs. |
flywheel executions:terminate | Close one stored execution record: sets its status to --terminal_status (completed, failed or canceled; omitted: canceled), merges --metadata into the record's metadata, and bumps the node's revision. It records status only: it stops no process or compute (release machines with compute:release). Needs the node's owner or an admin. Only a running record can be closed: one that is already completed, failed or canceled is refused with 409 naming its status, and stays as it is. |
Approvals & Budgets Commands
| Command | Summary |
|---|---|
flywheel approval-sessions:expire | Mark an approval session expired. Grants, leases and campaign budgets are untouched: machines keep running and keep billing until you release them with compute:release. Returns approval_session (now expired), reason (echoed back, not stored) and two lists, expired_compute_grant_ids and released_lease_ids, which are always empty (kept so older callers still find the fields). |
flywheel approval-sessions:heartbeat | Extend an existing approval session to --ttl_seconds from now (at least 60). Without --session_id, open a new session first, then refresh it. An unknown, someone else's or expired session fails. Returns approval_session with session_id, status, last_heartbeat_at, expires_at, user_id, created_at and updated_at, plus opened_session_id when opened. A call sooner than --min_touch_interval_seconds after the last one returns the session unchanged. |
flywheel approval-sessions:list | List your approval sessions, most recently updated first. Returns approval_sessions, each with the same session fields as approval-sessions:heartbeat. Use it to find a session_id, or sessions left open that you want to expire. |
flywheel campaign-budgets:create | Fund a campaign compute budget that participants on a root's graph draw from through their own grants. It needs hard_cap_cents of credit headroom: your balance minus what your other active campaign budgets still have uncommitted. Without it the call fails with Campaign budget commitment needs N cents, but only M cents are available. Returns budget (including compute_budget_id). Only the campaign's owner or an admin may create one. |
flywheel campaign-budgets:list | List the compute budgets funded for a campaign (a graph's root). Only the campaign's owner or an admin may call it. Returns budgets, each with compute_budget_id, status (active, exhausted or revoked), hard_cap_cents, per_user_hard_cap_cents, name, description, spent_cents, remaining_cents and timestamps. |
flywheel campaign-budgets:revoke | Mark a campaign budget revoked, so no new grant can be made from it. It does not stop spending already underway: participants' active grants and running leases continue until their own caps or credits run out; release leases with compute:release. Returns budget. |
flywheel campaign-budgets:update | Change a campaign budget's caps, name or description. Omitted fields stay as they are and at least one must be given. A revoked budget cannot be updated. Raising a cap needs the extra credit headroom, as creating one does. Returns budget. |
Export & Import Commands
| Command | Summary |
|---|---|
flywheel export:subgraph | Export nodes as one JSON document accepted by import:subgraph: version, exported_at, node_count and nodes (full records with content, summary, tags, artifacts and executions). Edges to nodes outside the export are dropped in both directions. --include_descendants adds visible descendants; exceeding --max_nodes fails with 422 export_node_limit_exceeded instead of a partial export. |
flywheel export:summary | Write a Markdown summary of selected nodes. Sends their non-empty summaries to an outside language model (OpenRouter by default, through LiteLLM) and bills usage to your credits (credits:balance). Empty summaries are left out; if all are empty, returns _No node content found in selected nodes._ without a model call or charge. Returns markdown and title. Of the five summary commands, nodes:render:summary and export:summary:render-pdf call no model and cost nothing; export:summary, export:summary:stream and export:summary:pdf call an outside language model and charge credits. |
flywheel export:summary:pdf | Write a model-backed summary as a PDF to the required --out path (--out=- writes to stdout). Sends selected nodes' non-empty summaries to an outside language model (OpenRouter by default, through LiteLLM) and bills usage to your credits (credits:balance). Empty summaries are left out; if all are empty, refuses with 400 and no charge. Usage is charged before PDF compilation, so a failed compile is still charged. The PDF embeds the selected nodes' full export:subgraph document in its metadata. Of the five summary commands, nodes:render:summary and export:summary:render-pdf call no model and cost nothing; export:summary, export:summary:stream and export:summary:pdf call an outside language model and charge credits. |
flywheel export:summary:render-pdf | Render supplied title and Markdown as a PDF with no model call and no charge. Requires --out and writes the PDF to that path (--out=- writes to stdout). The PDF embeds the selected nodes' full export:subgraph document in its metadata. For a model-written summary use export:summary:pdf. Of the five summary commands, nodes:render:summary and export:summary:render-pdf call no model and cost nothing; export:summary, export:summary:stream and export:summary:pdf call an outside language model and charge credits. |
flywheel export:summary:stream | Write the same model-backed summary as export:summary, streaming NDJSON events. Sends selected nodes' non-empty summaries to an outside language model (OpenRouter by default, through LiteLLM) and bills usage to your credits (credits:balance). Empty summaries are left out; if all are empty, emits one complete event with _No node content found in selected nodes._ and no model call or charge. Streams to stdout, or --out when given; unlike MCP, the CLI does not buffer the whole answer into one result. Of the five summary commands, nodes:render:summary and export:summary:render-pdf call no model and cost nothing; export:summary, export:summary:stream and export:summary:pdf call an outside language model and charge credits. |
flywheel import:subgraph | Import graph JSON as new nodes in one commit, reporting the repository and its visibility. |
Updates & Resources Commands
| Command | Summary |
|---|---|
flywheel blobs:get | Download a raw blob by storage key. |
flywheel machines:list | List your managed compute leases. |
flywheel updates:hide | Hide one announcement from your own updates list; other users still see it. Returns {success: true}; an unknown announcement_id is a 404, not success: false. Undo with updates:unhide. |
flywheel updates:hide-all-active | Hide every active announcement you have not already hidden, for you only. Returns hidden_count, the number newly hidden (0 when all were already hidden). Nothing is archived or deleted; restore one at a time with updates:unhide. |
flywheel updates:list | List in-app announcements, newest first. Returns items (announcement_id, title, body, published_at, status, hidden_at) and total_count. There is no has_more: raise --page until you have read total_count items. Hidden and archived announcements are left out. |
flywheel updates:unhide | Show a hidden announcement in your updates list again. Returns {success: true}, also when it was not hidden; an unknown announcement_id is a 404. |
Account & Credits Commands
| Command | Summary |
|---|---|
flywheel account:detach | Detach a linked alias account (requires confirm="DETACH"). Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel account:emails:add | Add an email alias to your account. Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel account:emails:remove | Remove an email alias from your account. Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel account:emails:set-primary | Set your primary email address. Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel account:get | View account snapshot and linked identities. |
flywheel account:merge | Execute an account merge (requires confirm="MERGE"). Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel account:merge:preview | Preview what an account merge will do. Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel account:merge:proof | Mint a merge proof token from a source session token. Requires a browser session; API-key callers receive session_auth_required with /app?settings=user. |
flywheel credits:balance | Read balance_cents, balance_dollars and lifetime_purchased_cents, lifetime_gifted_cents and lifetime_spent_cents; all are 0 when you have no credit record. Credits pay for managed compute and the model-backed exports export:summary, export:summary:stream and export:summary:pdf. |
flywheel credits:billing-portal | Open the Stripe billing portal for the current user and return browser_flow_required JSON with url, opened, and next_action. |
flywheel credits:purchase | Create a Stripe checkout session for a one-time purchase and return browser_flow_required JSON with url, opened, and next_action. |
flywheel credits:referral | View your referral code and status. |
flywheel credits:referral:claim | Claim referral rewards using a code. |
flywheel credits:subscribe | Create a Stripe checkout session for a subscription and return browser_flow_required JSON with url, opened, and next_action. |
flywheel credits:subscription | View your subscription status. |
flywheel credits:transactions | View paginated credit transactions. |
flywheel credits:usage | Feature-based usage breakdown over a window. |
Integrations Commands
| Command | Summary |
|---|---|
flywheel github:disconnect | Disconnect GitHub from your account. |
flywheel github:link | Start the GitHub App install/link browser flow. |
flywheel github:refresh-repos | Refresh the list of accessible repositories. |
flywheel github:status | Check GitHub connection status. |
flywheel integrations:huggingface:remove | Remove your Hugging Face credential. |
flywheel integrations:huggingface:set | Store a Hugging Face access token. |
flywheel integrations:status | Check integration connection status (W&B, Hugging Face). |
flywheel integrations:wandb:remove | Remove your W&B credential. |
flywheel integrations:wandb:set | Store a Weights & Biases API key. |
API Keys Commands
| Command | Summary |
|---|---|
flywheel api-keys:create | Create a new API key and return the raw material once. |
flywheel api-keys:delete | Delete an API key (refuses to delete the active one unless --allow-self). |
flywheel api-keys:list | List your API keys. |
flywheel api-keys:rotate | Rotate an API key (refuses to rotate the active one unless --allow-self). |
Other Commands
| Command | Summary |
|---|---|
flywheel compute-grants:list | List your compute grants: spending allowances, each tied to one approval session. Returns grants, each with compute_grant_id, approval_session_id, budget_source, compute_budget_id, grant_cents, spent_cents, remaining_cents, status (active or expired) and timestamps. A session ID that is unknown or not yours returns an empty list. |
flywheel compute-grants:request-approval | Ask for compute spending to be approved before you acquire. Returns one of three outcomes in status. already_approved: an active grant of this session with money left covers it; pass its compute_grant_id to compute:acquire. approval_required: a person must open and approve approval_url (it proposes suggested_hard_cap_cents), then call compute-grants:list with the same --approval_session_id until the grant is active. insufficient_credits: your credit balance is zero or below, so no grant funded from your own credits can be created; add credits (see credits:balance) and ask again. Every outcome also carries budget_source, grant_action and approval_session_id. It records the request and refreshes the session; it launches and spends nothing. |
flywheel feedback:create | Submit bounded feedback to the Flywheel team. |
flywheel update | Update the local Flywheel CLI package and setup artifacts |