Settings and commands

Repository settings describe setup, run, and archive behavior. These actions use the workspace's .farero/config.json; existing workspaces retain their own file. Editing the repository's configuration does not silently replace every existing workspace configuration.

Farero reads .farero/config.json from the repository or worktree. A committed file at the repository root supplies defaults for new workspaces; the file in a worktree applies to that workspace only. Existing workspaces keep their own file when repository settings change. All fields are optional.

{
  "setup": "yarn install",
  "runs": [
    {
      "id": "app",
      "name": "App",
      "command": "yarn dev",
      "icon": "globe",
      "previews": [
        {
          "name": "App",
          "url": "http://localhost:$PORT"
        }
      ]
    },
    {
      "id": "desktop",
      "name": "Desktop app",
      "command": "yarn dev:desktop",
      "icon": "monitor"
    }
  ]
}

Add a command to runs for each task you want in the Run menu. With more than one command, use the arrow beside Play to choose one. Play remembers the last choice for this workspace on this device; otherwise it uses the first command.

In this example, yarn dev starts the App and must read the PORT environment variable to choose its listening port. yarn dev:desktop starts a desktop app. Replace these commands with scripts from your project. Each command runs from the workspace folder.

Every entry needs a non-empty command. The name is the label shown in Farero. An omitted or blank id is generated from the name; if both are omitted, Farero uses run, then run-2, and so on. To keep an ID stable when you rename a command, include it explicitly. IDs must be unique and contain only letters, numbers, hyphens, or underscores, starting with a letter or number. The ID dev is reserved for the single run field.

Set icon to a Lucide icon name such as globe, book-open, or monitor. Use lowercase words separated by hyphens. The icon is optional.

Put previews used by one command inside that entry. Top-level previews apply to every command and are combined with its own previews. For a command that does not serve a webpage, omit its previews and keep global previews empty. Farero shows Stop while that task runs, and its output is available from the terminal button.

The single run string is still supported. If you use it alongside runs, it appears as an additional Dev choice and uses the global previews.

Preview entries tell Farero which local HTTP services to open and forward when you press Run. Name an entry to show it in the preview menu; leave out name to forward a companion service without adding a menu item. The command must start any services it needs.

Farero assigns each workspace a base port and replaces $PORT (or ${PORT}) in a preview URL with that number. $PORT+N and ${PORT+N} add N to the base port.

For example, if the base port is 8793, http://localhost:$PORT becomes http://localhost:8793 and http://localhost:$PORT+2 becomes http://localhost:8795. Your run command must start services that listen on those resulting ports.

Farero passes the base port to the selected command as the PORT environment variable. Configure your development server to read it, or pass it through the port option supported by your tool. $PORT+N and ${PORT+N} are preview URL placeholders; your command must calculate the offset and start the service on that port.

Use valid JSON: comments are not supported. Farero reads the current file when you use a configured action. It ignores unknown fields and rejects malformed JSON or invalid values for fields it recognizes before running the command.

Run commands on the computer hosting Farero:

farero
farero --help
farero service status

The first opens the local app. Help lists commands available in your installed version. Service status reports the login service's state.

farero config manages installation configuration, and farero mcp provides a stdio bridge for external MCP clients. Use the installed command's help for exact options. Supply secrets through the supported secret-input path rather than putting them in a command that will be saved in shell history.

You do not need source-checkout commands such as yarn dev to operate a managed installation. See Troubleshooting for a failing service or workspace setup.