Forge CLI

What it is

The Forge CLI manages identity, sync, and Agent helpers from a terminal.

Only Ready commands are active. Planned commands are labeled Future / Planned in the live command registry.

How to use it

Each command below says what it actually does and when to use it, followed by an example.

A typical first session: forge login (connect this computer to your account), forge init (link the folder to Forge), then forge push / forge pull to move changes between devices.

forge set saves the current project as a reusable template; forge run preset <name> starts a new project from it.

Do not treat Planned rows as shipping features.

Related features

• Terminal
• Getting Started

Command registry

• forge .What it does: Opens a folder in Forge Desktop. forge . opens it in the main (left) pane, forge .. opens it as a reference on the right, and forge ... uses the three-pane layout. Plain forge opens Desktop with no project.
  When to use it: Whenever you are in a terminal and want to edit that folder in Forge.
  Example: forge .Ready
• forge agent knowsWhat it does: Lists the parts of the project the Agent understands well, partly, or not at all (and what is out of date). --details shows the files behind each item.
  When to use it: To find gaps before asking the Agent about a part of the code.
  Example: forge agent knows --detailsReady
• forge agent refreshWhat it does: Rescans the project and updates the Agent's index for files that were added, changed, or deleted.
  When to use it: After big changes outside Forge (a pull, a branch switch, generated code) so the Agent sees current code. Use --files to refresh only some paths.
  Example: forge agent refreshReady
• forge agent reindexWhat it does: Exactly the same as forge agent refresh.
  When to use it: Use whichever name you remember.
  Example: forge agent reindexReady
• forge agent statusWhat it does: Shows how much of the project the Agent has indexed and remembers, plus whether it can see Git state and diagnostics.
  When to use it: When Agent answers seem uninformed and you want to know what it can see.
  Example: forge agent statusReady
• forge agent whyWhat it does: Shows which files and notes the Agent pulled in for its most recent answer.
  When to use it: When an answer looks wrong and you want to see what it was based on.
  Example: forge agent whyReady
• forge auth statusWhat it does: Prints which Forge account and device this terminal is signed in as. It never prints the token itself.
  When to use it: When a command says you are not signed in, or you are unsure which account is active.
  Example: forge auth statusReady
• forge commandsWhat it does: Prints every Forge command grouped by category and marks each one Ready or Planned.
  When to use it: When you forget a command name or want to know whether something works yet.
  Example: forge commands --status readyReady
• forge designWhat it does: Takes a description of what you want to build and finds the most relevant capabilities from your past projects to reuse.
  When to use it: When planning a feature and you suspect you already solved part of it elsewhere. Requires Pro or higher.
  Example: forge design "team invite flow"Ready
• forge env checkWhat it does: Confirms that the named secrets exist and that you can read them, without printing their values.
  When to use it: Before a build or deploy, or when something fails with a missing variable.
  Example: forge env check DATABASE_URL,STRIPE_KEYReady
• forge env listWhat it does: Lists the names of the secrets (environment variables) stored for this project in Forge Secrets.
  When to use it: To check which variables a project has before running or deploying it.
  Example: forge env list --env productionReady
• forge env removeWhat it does: Deletes one secret from the project's environment in Forge Secrets.
  When to use it: When a key is retired or was added by mistake.
  Example: forge env remove OLD_TOKENReady
• forge env setWhat it does: Creates or changes one secret. It asks for the value at a prompt, so the value does not end up in your shell history.
  When to use it: When you add an API key or change a configuration value for a project.
  Example: forge env set STRIPE_KEYReady
• forge featuresWhat it does: Shows which Forge features are switched on for your account, using a cached copy when you are offline. `forge features check <id>` exits 0 when a feature is on.
  When to use it: After a feature was enabled for you, or in scripts that should only run when a feature is on. Add --refresh to skip the cache.
  Example: forge features --refreshReady
• forge initWhat it does: Turns the current folder into a Forge project. In an existing project it writes .forge/project.json and links it to your account. In an empty folder it can also create starter files from your New Project Defaults.
  When to use it: Once per project, before push, pull, sync, or Agent commands. Use --repair when the folder is linked to a cloud project that no longer exists.
  Example: forge init my-appReady
• forge inspect architectureWhat it does: Checks the project against its architecture rules and reports a health score with the evidence for each finding.
  When to use it: Before a release or a large refactor, to catch structural drift. Requires Pro or Premium.
  Example: forge inspect architectureReady
• forge learn capabilitiesWhat it does: Lists learned capabilities across all your projects, optionally filtered by category.
  When to use it: When looking for something you built before that could be reused.
  Example: forge learn capabilities --category authReady
• forge learn inspectWhat it does: Shows the learned capabilities and architecture rules for this project in detail.
  When to use it: When you want to review or verify what Forge believes about the project's structure.
  Example: forge learn inspectReady
• forge learn rebuildWhat it does: Re-extracts this project's reusable capabilities from the current Agent index. It does not rescan files.
  When to use it: After forge agent refresh, when learned capabilities look stale.
  Example: forge learn rebuildReady
• forge learn statusWhat it does: Shows what Forge has learned from this project so far: how many reusable capabilities and recent learning events.
  When to use it: To check whether learning ran and is up to date for this project.
  Example: forge learn statusReady
• forge library addWhat it does: Adds one specific project folder to your Forge Library: links it to Forge if needed and indexes it for the Agent. It does not look inside for other projects and does not touch Git.
  When to use it: When you have an existing project you want Forge and the Agent to know about.
  Example: forge library add ~/code/apiReady
• forge library importWhat it does: Scans a parent folder for projects and adds the new ones to your Forge Library in one go. It shows a preview first and skips projects already added.
  When to use it: When you have a folder full of projects (for example ~/code) and want them all in Forge. Use --dry-run to only preview.
  Example: forge library import ~/code --dry-runReady
• forge loginWhat it does: Connects this terminal to your Forge account. It opens a browser page where you approve the device, then saves a device credential on this computer so later commands know who you are.
  When to use it: The first time you use the CLI on a computer, or after forge logout. Use --status to see whether you are already signed in.
  Example: forge loginReady
• forge logoutWhat it does: Signs this terminal out. It revokes the saved device credential on the server and deletes it from this computer.
  When to use it: On a shared or old machine, or when you want to sign in as a different account.
  Example: forge logoutReady
• forge modesWhat it does: Prints the list of Forge Modes (specialized workspaces such as web or gaming) and whether each is ready or planned.
  When to use it: To see which modes exist and which are still previews.
  Example: forge modesReady
• forge pairWhat it does: Pairs Forge Mobile with this computer. On Desktop it asks the open Forge window to show a 6-character code; on Mobile you enter that code. Pairing trusts the device, not one specific project.
  When to use it: Once per Mobile device, before Send to Desktop or running commands from Mobile on this computer. Forge Desktop must be open on the folder.
  Example: forge pairReady
• forge presetWhat it does: Manages one saved preset: show what is in it, update it from the current project, delete it, apply it to make a new project, or export/import it as a file to move between computers.
  When to use it: When you need to inspect, clean up, or share a preset. forge set creates presets; this command maintains them.
  Example: forge preset show my-next-starterReady
• forge presetsWhat it does: Lists the presets saved on this computer.
  When to use it: To see which templates you can start from, or to find a preset's exact name.
  Example: forge presetsReady
• forge pullWhat it does: Downloads the latest cloud version of the project into this folder and records it, so the pulled files are not mistaken for your own edits.
  When to use it: When you changed the project on another device and want those changes here.
  Example: forge pullReady
• forge pushWhat it does: Uploads your local changes to Forge Cloud and saves them as the next version of the project. This is Forge sync, separate from git push.
  When to use it: When you want your latest work available on your other devices (Mobile, another Desktop).
  Example: forge push --message "nav fixes"Ready
• forge runWhat it does: Creates a brand-new project in a new folder (native, Next.js, React, or one of your presets), links it to Forge, and opens it in Forge Desktop.
  When to use it: When you are starting something new and want the folder, Forge link, and Desktop window set up in one step.
  Example: forge run next my-siteReady
• forge sendWhat it does: From Forge Mobile, creates or links the current project on your paired Desktop so you can keep working on it there.
  When to use it: When a project started on Mobile should continue on your computer. You need to have run forge pair first.Ready
• forge setWhat it does: Saves the current project as a reusable template (a preset): which files, packages, and scripts it has. It is a recipe, not a zip, and it never includes secrets or node_modules.
  When to use it: When you have a project setup you like and want to start future projects from it with forge run preset <name>. Run it again with -y to save a new version.
  Example: forge set "my-next-starter"Ready
• forge statusWhat it does: Compares this folder with the latest version saved in Forge Cloud and lists files you changed locally since then.
  When to use it: Before push or pull, to see whether you are ahead, behind, or in sync.
  Example: forge statusReady
• forge syncWhat it does: Checks this folder against Forge Cloud and, if you have no local changes and your preference allows it, pulls the newer cloud version automatically. It never overwrites unsaved local work.
  When to use it: As a quick 'catch me up' when you move between devices.
  Example: forge syncReady
• forge <mode>What it does: Planned: opens a preview workspace for a mode (for example forge web). It is a static preview and does not start a real specialized runtime.
  When to use it: Only to look at where a mode is heading.Planned
• forge bind <projectId>What it does: Planned: attach this folder to an existing Forge project by ID.
  When to use it: Not available yet. Use forge init or forge init --repair instead.Planned
• forge castWhat it does: Reserved name for a future Git Bridge command. It does nothing useful yet.
  When to use it: Not available yet.Planned
• forge fuseWhat it does: Reserved name for a future Git Bridge command. It does nothing useful yet.
  When to use it: Not available yet.Planned
• forge mineWhat it does: Reserved name for a future Git Bridge command. It does nothing useful yet.
  When to use it: Not available yet.Planned
• forge smithWhat it does: Planned: build from an approved forge design plan. It is still rolling out and is not fully autonomous yet.
  When to use it: Not for everyday use yet.Planned
• forge temperWhat it does: Reserved name for a future Git Bridge command. It does nothing useful yet.
  When to use it: Not available yet.Planned