The CLI

The package on npm is torta-ai, which installs the torta command. Run torta on its own for a one-line hint.

torta start

torta start [<dir>] [--port <n>] [--no-open] [--no-engine] [--runner <mode>]

With no workspace in the directory it serves the setup wizard, then opens the board of the workspace it creates. Pointed at a workspace, it opens that board.

The wizard’s first page asks what is being set up. Something new is seven pages (the fork, five questions, a summary); a folder that already has code in it is eight, with the reading of the folder and the ownership question inserted after the location, and no build question, since platforms follow from what was adopted. Adoption ends in torta adopt’s own code, not the create path.

Flag	Default	Meaning
--port <n>	5599	the port to serve on, a whole number from 0 to 65535
--no-open	off	do not open a browser
--no-engine	off	board only, no dispatching
--runner <mode>	auto	stub, sdk, pty or auto

<dir> is resolved against the current directory and has to exist. A workspace is looked for there and one level below. A named directory is also the parent the wizard offers; with nothing named, it offers ~/Documents/projects.

Ctrl-C stops the board, the engine and every pane. A second Ctrl-C exits at once with code 130. It serves 127.0.0.1 only.

Refusals: an unknown flag, a bad port, an unknown runner name, or a directory that does not exist. A port already in use says so and suggests --port <n>.

torta init

torta init
torta init <name> [--ios] [--android] [--web] [--desktop] [--landing] [--backend]
                  [--preset solo|full-team] [--role <what you are>]
                  [--owner <gh-owner>] [--dir <parent>] [--dry-run] [--yes]

With no name and no platform flags, it asks the wizard’s five questions in the terminal, without the fork in front of them: torta init creates and torta adopt adopts, so the command is already the answer. The queues come up empty; the first ticket is written by an agent you talk to on the board. With a name, it creates the workspace and stamps the workflow into it without asking.

Flag	Meaning
--ios, --android, --web, --desktop, --landing, --backend	the platforms to build, opt-in
--preset solo|full-team	the roster: three agents, or all eight
--role <what you are>	what you are on this project
--owner <gh-owner>	the GitHub owner for the repos
--dir <parent>	the parent directory the name joins onto, default the current directory
--dry-run	work out the workspace without writing it
--yes, -y	take the default for every question that has one

An unknown --flag that is not a platform is refused by name. Turning a platform off removes its repo, its agent’s home, its wall and its queue.

torta adopt

torta adopt [<dir>] [--as <owner>|none] [--preset solo|full-team]
                    [--role <what you are>]
                    [--name <workspace>] [--owner <gh-owner>] [--<platform>]
                    [--yes] [--dry-run] [--undo] [--resume]

Put a workspace around projects you already have. <dir> defaults to the current directory. That folder becomes the workspace root, and each project moves into .projects/ with its own .git and its whole history. Nothing already in the folder is overwritten, and ADOPTED.md records who owns what, every move, every merge, every kept-both copy and the command that reverses all of it.

A Claude Code session reads the folder and says which agent owns each project it finds: frontend, backend, qa, infra, archi, product or growth. The stack does not matter. Each answer comes with a plain sentence saying why, and you may change any of them. A project it will not place is left exactly where it is and reported.

Bare, it asks the same questions the wizard asks, one at a time, with two more in the middle: the reading, which is a read, and one ownership question per project it found.

Read the plan before anything moves. This writes nothing:

torta adopt ~/Documents/projects/my-app --dry-run

Flag	Meaning
--as <owner>|none	who owns a project. Repeat it once per project, in the order they were found. Saying it for all of them skips the reading. --as none leaves that project exactly where it is, and at least one project must still be adopted
--name <workspace>	the workspace name. Default: the folder’s own name, lowercased with hyphens
--preset solo|full-team	the roster: three agents, or all eight
--role <what you are>	what you are on this project
--owner <gh-owner>	the GitHub owner. Default: the owner in the project’s origin remote
--ios, --android, --web, --desktop, --landing, --backend	one more thing the workspace ships, on top of what the adopted projects turn on by themselves
--dry-run	print the whole plan and write nothing
--yes, -y	take the default for every question, and adopt without asking
--undo	put the folder back exactly as it was
--resume	finish a move that stopped part way

--dry-run calls the same function the wizard’s summary page calls, so the terminal and the browser cannot disagree about what is going to happen.

The reading is not asked for: torta refuses to run without Claude Code installed and signed in, so one read-only session on the folder you named is part of adoption. It is announced as it starts, at both doors.

Refusals, each naming what was actually found: nothing in the folder to adopt, a folder too large to read at adoption time, a reading that answered nothing usable, a word that is not an owner, two projects sent to one repository, every project declined, a folder that is already a workspace or sits inside one, your home folder, and the root of the disk. Nothing is written by any of them.

torta watch

torta watch [<dir>] [--cap <n>] [--runner stub|sdk|pty|auto] [--busy <agent>] [--once]

The engine, standalone. torta start runs it for you; reach for it on a server with no board, or for --runner stub and --runner sdk in CI.

Flag	Default	Meaning
--cap <n>	3	how many sessions may run at once, at least 1
--runner <mode>	stub	stub, sdk, pty or auto
--busy <agent>	none	an agent you are driving by hand. Repeatable
--once	off	run one pass, then stop

--busy must name an agent in this workspace’s roster, and the refusal lists the roster. If an engine is already running here, it refuses and names the command that holds it.

Ctrl-C stops watching. Sessions already running are left to finish.

torta board

torta board [<dir>] [--port <n>]

The board without the engine: every queue, the statuses, the access map, the accounts this project still needs, the decisions waiting on you, and a pane per agent. Approving here starts nothing until an engine is running.

torta pending

torta pending [<dir>]

For each open decision it prints the ticket, the file, the question, the agent, the status, when it was asked, and the reason if there is one. When nothing is waiting it says so and exits 0.

torta approve and torta reject

torta approve [<dir>] <ticket> [--reason <why>]
torta reject  [<dir>] <ticket> [--reason <why>] [--interrupt]

Make the transition the session stopped to ask about, or send it back for changes. --interrupt on reject stops the running session instead of sending the ticket back. Without a ticket, it prints the usage line and exits 1.

torta sync

torta sync [<dir>]

Regenerate the walls and the briefs after editing torta.json. It carries the generators across into the workspace first, makes any .projects/ directory torta.json declares that is not there yet, and stamps the home, the brief and the queues of any agent the roster has gained, so an agent turned back on can be given a ticket.

torta doctor

torta doctor [<dir>]

Check the config, and what each agent still needs to work.

torta verify

torta verify [<dir>]

Assert that the generated walls match the committed lock.

torta status

torta status

What this machine has: the torta version, the Node version, the python it found, the platform and architecture, the package root, and a file count for the engine, the profiles and the templates.

torta help and torta version

torta help, -h and --help print the manual. torta version, -v and --version print the version. Both exit 0.

Exit codes

Code	Meaning
0	it worked
1	the general refusal: a bad flag, a missing workspace, a refused decision
2	not a torta command
130	a second Ctrl-C while shutting down

start, board, watch and the interactive init do not exit on their own.

Where a command may run

Every command except start, init, adopt and status takes an optional directory and refuses if that directory has no torta.json, with the message <dir> has no torta.json. With no directory, the current one is used. torta adopt is the inverse: it insists the folder is there and refuses one that already holds a workspace.