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 201 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 | Show authentication status for the current client context. |
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 | Fetch one artifact metadata record. |
flywheel hosted:artifact:list | List artifacts for a node. |
flywheel hosted:artifact:set-metadata | Commit a replacement for exactly one artifact metadata field from --metadata-file or one inline flag. |
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. |
flywheel hosted:lineage:list | Page direct visible parents or children for one node. |
flywheel hosted:lineage:remove | Commit the removal of a lineage relation. |
flywheel hosted:node-tag:assign | Commit assigning a tag to a node. |
flywheel hosted:node-tag:remove | Commit removing a tag from a node. |
flywheel hosted:node:branch | Create one branched node and one lineage relation from the source, copying the source's title. Without --repository-id the server places it in the source's repository when you hold a write role there, otherwise in your fork of that repository, where the node starts private unless you have added members to that fork. 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 write role there, otherwise in your fork of that repository, where the node starts private unless you have added members to that fork; with no --parent, as a root in your default workspace. With --repository-id, commit a root node in that hosted repository. |
flywheel hosted:node:get | Fetch one node by identifier. Use relationship paging commands for complete direct-neighbor traversal. |
flywheel hosted:node:list | List nodes with optional filters. |
flywheel hosted:node:merge | Commit one merged node in this hosted repository and one lineage relation from each supplied source, in argument order. |
flywheel hosted:node:restore | Commit the restoration of a tombstoned node; retained semantic edges never block it. |
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. |
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. |
flywheel hosted:tag:retire | Commit the retirement of a tag definition. |
flywheel hosted:tag:update | Commit a changed tag definition. |
Nodes & Graph Commands
| Command | Summary |
|---|---|
flywheel campaign:snapshot | Resolve campaign root snapshot for a node. |
flywheel graph:get | Read the graph projection for navigation and topology workflows. |
flywheel nodes:files | List files attached to a node. |
flywheel nodes:render:ancestry | Render ancestry (roots-ward lineage) for a node. |
flywheel nodes:render:summary | Render a compact summary of a node subtree. |
flywheel nodes:render:tree | Render a bounded tree projection for a node. |
flywheel nodes:resolve-slug | Resolve a slug to a node ID. |
flywheel nodes:sharing:get | Get sharing (access policy) for a node. |
flywheel nodes:sharing:set | Replace sharing (access policy) for a node. |
flywheel nodes:sharing:set-bulk | Apply one sharing policy to up to 1000 nodes, all or nothing. |
flywheel nodes:sharing:summaries | Read access summaries for multiple nodes in one batch. |
flywheel nodes:stage:lease:acquire | Acquire an edit lease for an existing node. |
flywheel nodes:stage:lease:heartbeat | Heartbeat an active node stage lease. |
flywheel nodes:stage:lease:release | Release a node stage lease. |
flywheel remote-artifacts:refresh | Force refresh a public HTTPS JSON Remote Artifact for a node. |
flywheel remote-artifacts:resolve | Resolve a public HTTPS JSON Remote Artifact for a node. |
Artifacts & Files Commands
| Command | Summary |
|---|---|
flywheel files:list | List all your files across nodes. |
Hooks Commands
| Command | Summary |
|---|---|
flywheel hooks:create | Create a new hook on an owner node. |
flywheel hooks:delete | Delete a hook from an owner node. |
flywheel hooks:list | List hooks configured for an owner node. |
flywheel hooks:runs:list | List hook runs for an owner node. |
flywheel hooks:secrets:create | Create a hook secret. |
flywheel hooks:secrets:delete | Delete one hook secret. |
flywheel hooks:secrets:list | List hook secret metadata for an owner node. |
flywheel hooks:secrets:update | Rotate one hook secret value. |
flywheel hooks:set-enabled | Enable or disable an existing hook. |
flywheel hooks:update | Update mutable hook fields for an existing hook. |
Compute & Executions Commands
| Command | Summary |
|---|---|
flywheel compute:acquire | Acquire managed compute for a node; with --wait, wait for usable SSH connection material. |
flywheel compute:budgets | List budget grants visible for a node context. |
flywheel compute:connection | Get SSH connection material for a usable lease. |
flywheel compute:funding | Read grant-scoped funding context before compute acquire. |
flywheel compute:options | List allowed compute catalog options for a node. |
flywheel compute:release | Release one active compute lease (async; use --wait to block). |
flywheel compute:release-all | Release all active leases in current scope (pass --force for account scope). |
flywheel compute:status | Return compute lease status. |
flywheel executions:launch | Start an execution for a node. |
flywheel executions:list | List executions for a node. |
flywheel executions:terminate | Stop an execution for a node. |
Approvals & Budgets Commands
| Command | Summary |
|---|---|
flywheel approval-sessions:expire | Expire an approval session. |
flywheel approval-sessions:heartbeat | Create or refresh a compute approval session. |
flywheel approval-sessions:list | List approval sessions. |
flywheel campaign-budgets:create | Create a campaign compute budget grant. |
flywheel campaign-budgets:list | List campaign compute budgets for a root. |
flywheel campaign-budgets:revoke | Revoke a campaign budget grant. |
flywheel campaign-budgets:update | Update a campaign budget. |
Export & Import Commands
| Command | Summary |
|---|---|
flywheel export:subgraph | Export a subgraph snapshot. |
flywheel export:summary | Generate a markdown summary export. |
flywheel export:summary:pdf | Render summary as PDF; requires --out. |
flywheel export:summary:render-pdf | Render caller-provided markdown as PDF; requires --out. |
flywheel export:summary:stream | Stream summary generation as NDJSON events. |
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 a specific announcement. |
flywheel updates:hide-all-active | Hide all currently active announcements. |
flywheel updates:list | List in-app announcements relevant to your account. |
flywheel updates:unhide | Restore a previously hidden announcement. |
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 | View credit balance and totals. |
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 compute grants available to the user. |
flywheel compute-grants:request-approval | Request compute-grant approval. POSTs to the consolidated server endpoint which owns the heartbeat/grants/credits/campaign-budgets/status fan-out. |
flywheel feedback:create | Submit bounded feedback to the Flywheel team. |
flywheel update | Update the local Flywheel CLI package and setup artifacts |