skills/flutterflow-designer/orbit-commands.md

FF Orbit Command Reference

Complete reference for all Orbit MCP commands. The primary MCP tool is orbit():

orbit({ cmd: "<command>", args?: {}, snapshot?: "<id>", format?: "json"|"explain" })

Supporting tools: orbit_policy_get(), orbit_policy_set(), orbit_export_changeset()

---

Architecture

Orbit is snapshot-first:

• Snapshot: Local point-in-time copy of project files (cached in SQLite)
• Index: Symbols and edges extracted from snapshot for fast search
• Changeset: Draft edits with preview, validation, and apply lifecycle

Prefer deterministic first-class commands over exploratory probing. Use help when command shape is unclear.

---

Discovery Commands

Command	Purpose	Example Args
help	List all commands or get help for specific command	{ cmd: "widget.create" }
api.capabilities	Check FlutterFlow API connectivity	—
projects.list	List accessible FlutterFlow projects	—

---

Snapshot Commands

Command	Purpose	Key Args
snapshots.create	Create snapshot from a project	{ projectId: "..." }
snapshots.refresh	Update snapshot with latest files	{ mode, fetchStrategy, maxFetch, concurrency, sleepMs }
snapshots.refreshSlow	Throttled refresh for rate-limited scenarios	{ passes, maxFetch, concurrency, sleepMs, pauseMs }
snapshots.ensureFresh	Refresh only if older than threshold	—
snapshots.info	Show snapshot metadata	—
snapshots.ls	List all snapshots	—

Refresh Strategies

Scenario	Args
Normal incremental	{ mode: "incremental", fetchStrategy: "auto", maxFetch: 25, concurrency: 1, sleepMs: 250 }
Heavy rate limiting	{ mode: "incremental", fetchStrategy: "file", maxFetch: 5, concurrency: 1, sleepMs: 1000 }
Full sync	{ mode: "full", fetchStrategy: "bulk" }
Chunked full fallback	{ mode: "full", fetchStrategy: "file", maxFetch: 5 }

---

Page Commands

Command	Purpose	Key Args
pages.list	List all pages	{ includeDeleted?, strictSnapshot? }
page.get	Get full page details (widget tree)	{ nameOrId }
page.create	Create a new blank page	{ name, apply? }
page.scaffold	Generate page from built-in recipe	{ recipe, name, apply? }
page.update	Update page properties	{ nameOrId, key, value, apply? }
page.clone	Duplicate a page	{ nameOrId, newName, apply? }
page.preflightDelete	Check what would break before deleting	{ nameOrId }
page.remove	Safe delete with checks	{ nameOrId, apply? }
page.delete	Low-level delete (no safety checks)	{ nameOrId, apply? }

Built-In Page Recipes

Recipe	Description
auth.login	Login page with email/password fields
auth.signup	Signup page with registration fields
settings.basic	Settings page with toggles and list tiles
list.cards.search	List with search bar and card items
detail.basic	Detail page with header and content

Examples

# Create page
orbit({ cmd: "page.create", args: { name: "SplashScreen", apply: true } })

# Rename page
orbit({ cmd: "page.update", args: { nameOrId: "SplashScreen", key: "name", value: "Splash", apply: true } })

# Safe delete
orbit({ cmd: "page.remove", args: { nameOrId: "OldPage", apply: true } })

# Scaffold from recipe
orbit({ cmd: "page.scaffold", args: { recipe: "auth.login", name: "LoginPage", apply: true } })

---

Widget Commands — Read

Command	Purpose	Key Args
widgets.list	List widgets on a page	{ nameOrId, type?, include? }
widgets.find	Search by type, text, or properties	{ nameOrId, ... }
widgets.findText	Search widgets containing text	{ nameOrId, text }
textfields.list	List all text field widgets	{ nameOrId }
widget.get	Get single widget by node ID	{ nameOrId, nodeId }
widget.getMany	Get multiple widgets	{ nameOrId, nodeIds: [...] }

---

Widget Commands — Write

Command	Purpose	Key Args
widget.create	Create a new widget	{ nameOrId, type, parentNodeId?, apply? }
widget.insert	Insert at specific position	{ nameOrId, type, parentNodeId, beforeNodeId?, afterNodeId?, apply? }
widget.set	Update widget properties	{ nameOrId, nodeId, text?, props?, apply? }
widget.delete	Delete a widget	{ nameOrId, nodeId, apply? }
widget.deleteSubtree	Delete widget and all children	{ nameOrId, nodeId, apply? }
widget.duplicate	Duplicate a widget	{ nameOrId, nodeId, count?, apply? }

---

Widget Commands — Structure

Command	Purpose	Key Args
widget.wrap	Wrap widget in new parent	{ nameOrId, nodeId, wrapperType, apply? }
widget.unwrap	Remove wrapper, promote children	{ nameOrId, nodeId, apply? }
widget.move	Move to new parent	{ nameOrId, nodeId, newParentNodeId, apply? }
widget.moveMany	Move multiple widgets	{ nameOrId, nodeIds, newParentNodeId, apply? }
widget.reorder	Change position among siblings	{ nameOrId, nodeId, position, apply? }
widget.replaceType	Change widget type in place	{ nameOrId, nodeId, newType, apply? }
widget.removeChildren	Remove all children	{ nameOrId, nodeId, apply? }

---

Widget Commands — Batch

Command	Purpose	Key Args
widgets.updateMany	Batch update matching widgets	{ nameOrId, filter, updates, apply? }
widgets.copyPaste	Copy widgets between locations	{ ... }

---

Widget Actions & Data Binding

Command	Purpose	Key Args
widget.action.list	List actions on a widget	{ nameOrId, nodeId }
widget.action.get	Get specific action by trigger	{ nameOrId, nodeId, trigger }
widget.bindAction	Bind action to widget trigger	{ nameOrId, nodeId, trigger, action, apply? }
widget.bindData	Bind data to widget property	{ nameOrId, nodeId, property, binding, apply? }

---

Component Commands

Command	Purpose	Key Args
component.get	Get component details	{ nameOrId }
component.instance.insert	Insert component instance	{ nameOrId, componentId, parentNodeId, apply? }
component.extractFromWidget	Extract widget into component	{ nameOrId, nodeId, componentName, apply? }

---

Widget Tree Commands

Command	Purpose	Key Args
tree.locate	Find widget position in tree	{ nameOrId, nodeId }
tree.subtree	Get subtree rooted at widget	{ nameOrId, nodeId }
tree.find	Search tree (alias for locate)	{ nameOrId, ... }
tree.validate	Check tree integrity	{ nameOrId }
tree.repair	Fix tree issues	{ nameOrId, apply? }

---

Navigation & Routes

Command	Purpose	Key Args
routes.list	List all routes	—
routes.listByPage	Routes for a specific page	{ nameOrId }
routes.validate	Validate routes	{ nameOrId }
routes.upsert	Create or update route	{ from, to, trigger?, apply? }
routes.delete	Delete a route	{ routeId, apply? }
graph.nav	Query navigation graph	{ ... }
graph.usage	Query component usage graph	{ ... }

---

Search & Utility

Command	Purpose	Key Args
search	Full-text search across snapshot	{ query }
selection.get	Get current sticky selection	—
selection.clear	Clear sticky selection	—
intent.run	Natural language → command	{ text: "..." }
settings.get	Get project settings	—

---

Summaries

Command	Purpose	Key Args
summarize.page	Human-readable page summary	{ nameOrId }
summarize.component	Component summary	{ nameOrId }
summarize.project	Project overview	—

---

Changeset Commands

The changeset pipeline ensures safe writes:

Command	Purpose	Key Args
changeset.new	Create draft changeset	—
changeset.add	Add patch to changeset	{ changesetId, patches }
changeset.preview	Generate diffs and risk score	{ changesetId }
changeset.validate	Validate YAML + policy	{ changesetId }
changeset.apply	Apply changeset to FlutterFlow	{ changesetId, confirm }
changeset.applySafe	Apply with rate-limit retry	{ changesetId, confirm, rateLimitRetries?, rateLimitBaseMs?, rateLimitMaxWaitMs? }
changeset.rollback	Undo most recent changeset	{ changesetId }
changeset.revert	Revert snapshot to pre-changeset	{ changesetId }
changeset.drop	Discard draft changeset	{ changesetId }

Safe Write Workflow

1. orbit({ cmd: "changeset.new" })                           → get changesetId
2. orbit({ cmd: "changeset.add", args: { changesetId, patches: [...] } })
3. orbit({ cmd: "changeset.preview", args: { changesetId } })  → review diffs
4. orbit({ cmd: "changeset.validate", args: { changesetId } }) → check structure
5. orbit({ cmd: "changeset.applySafe", args: { changesetId, confirm: true } })

Rate-Limited Apply

orbit({ cmd: "changeset.applySafe", args: {
  changesetId: "chg_...",
  confirm: true,
  rateLimitRetries: 3,
  rateLimitBaseMs: 1500,
  rateLimitMaxWaitMs: 90000
}})

---

Schema Knowledge Base

Command	Purpose	Key Args
schema.search	Search built-in docs and snippets	{ query }
schema.read	Read specific doc by ID	{ id }
schema.snippet	Get code snippet by ID	{ id }

Use only for unfamiliar patterns or advanced debugging — not for routine operations.

---

Prompt-to-Command Quick Map

User Says	Command
"List pages"	pages.list
"Show widgets on login"	widgets.list { nameOrId: "login" }
"All text fields on login"	textfields.list { nameOrId: "login" }
"Get this widget"	widget.get { nameOrId, nodeId }
"Change text on widget"	widget.set { nameOrId, nodeId, text: "..." }
"Create a button under container"	widget.insert { nameOrId, type, parentNodeId }
"Remove widget"	widget.delete { nameOrId, nodeId }
"Rename page X to Y"	page.update { nameOrId, key: "name", value: "Y" }
"Refresh from FlutterFlow"	snapshots.refresh { mode: "incremental" }
"Wrap in column"	widget.wrap { nameOrId, nodeId, wrapperType: "Column" }
"Move widget under X"	widget.move { nameOrId, nodeId, newParentNodeId }
"Duplicate widget"	widget.duplicate { nameOrId, nodeId }
"Safe apply"	changeset.applySafe { changesetId, confirm: true }

Always return resolved IDs (snapshotId, pageId, nodeId, fileKey) in responses.