Installing and starting

The setup line printed nothing, or a curl error

The one line from the home page is:

/bin/bash -c "$(curl -fsSL https://docs.torta.app/install.sh)"

If the download fails, curl prints a short error and nothing else runs, because there was nothing to run. Nothing on your computer was changed.

• “Could not resolve host” means this computer is not online, or a company network is blocking it. Reconnect and paste the line again.
• Nothing at all happened: the line was pasted without its last character. Copy it again, and check it ends with )".
• “curl: command not found”: rare. Install curl, or follow the by-hand steps instead.

To read the script before running it, open docs.torta.app/install.sh in a browser.

The setup asked for my password

Only one step asks: installing Node on a Mac that has no Homebrew. Node goes into a folder shared by everyone on the computer, so macOS asks you to confirm you are allowed to put it there. It is your normal login password.

Nothing appears on screen as you type it. No dots, no stars, no moving cursor. That is how a terminal takes a password. Type it and press Enter.

The setup never asks for a password for anything else. Claude Code and torta install wherever npm already puts things, as long as that is a folder you can write to. When it is not, the setup switches to ~/.torta/npm, which you own, rather than asking you for a password.

torta: command not found, right after the setup finished

This only happens when the setup had to move your install folder, which it does only when the folder npm was using is not one you can write to. In that case it appended one line to your ~/.zshrc, or ~/.bashrc on bash:

export PATH="$HOME/.torta/npm/bin:$PATH"

A terminal window reads that file when it opens, and never again. The window you ran the setup in was opened before the line existed, so it does not know.

Close that window, open a new one, and the command is there. The setup itself does not need this, which is why it can still reach torta start on the first run.

What the setup check reports

To see what is installed without changing anything:

/bin/bash -c "$(curl -fsSL https://docs.torta.app/install.sh)" -- --check

It prints one row each and then stops:

• Computer: the system and chip, and whether the setup supports it.
• Node and npm: here with a version, too old, or not here yet.
• Tools install into: where a global install lands now, and whether it is a folder you can write to. Writable means the setup leaves it alone. Not writable is the case that causes permission errors, so the setup switches.
• Your own folder: whether ~/.torta/npm exists, and whether it is being used at all. On most machines it is never needed.
• PATH line: whether that line is in your shell profile, and whether it is needed.
• Claude Code: not here, here but not signed in, or here and signed in.
• torta: installed globally, or fetched by npx each time it starts.

It changes nothing, makes no folder and installs nothing, so it is safe to run whenever something looks wrong.

command not found: npm

Node is not installed, or the terminal window was already open before you installed it.

Close the terminal window, open a new one, and try again. If it still says this, install Node from nodejs.org and take the big green download button.

permission denied, or EACCES, on a global install

Your computer wants permission to install into a shared folder. Install with sudo:

sudo npm install -g @anthropic-ai/claude-code

Then run claude on its own to sign in. The same applies to sudo npm install -g torta-ai.

To avoid sudo altogether:

npx -y torta-ai start

Claude Code is not on this machine’s PATH

Install it:

npm install -g @anthropic-ai/claude-code

or use the native installer from the Claude Code page.

Claude Code is installed, but nobody is signed in

Run claude in a terminal and sign in. Type /exit to leave the chat afterwards.

This machine cannot say whether it is signed in

The probe checks an API key in the environment, a credentials file and a keychain entry, and none could answer. Torta carries on; if a session then fails to start, run claude once and sign in.

A red wall of text

Copy the last few lines and ask about them.

torta: has no torta.json

Every command except start, init and status refuses this way when the directory is not a workspace. Point it at the folder the wizard created:

torta pending ~/Documents/projects/my-project

torta start opens the wizard instead of refusing, looking in the directory you named and one level below it, never deeper.

torta: does not exist

Torta creates the workspace folder itself, but not the folders above it.

torta: unknown flag –thing

See the CLI reference for the flags each command takes. torta init also refuses a platform flag it does not know, by name.

torta: –port takes a port number, e.g. –port 5599

The port has to be a whole number from 0 to 65535.

port 5599 is already in use

Another board is probably running. Stop it, or pass --port <n>.

torta: has no workflow installed

The workspace has no generators for sync, verify and doctor to run. It is probably not a torta workspace, or was only partly copied.

torta adopt refuses the folder you pointed it at

torta adopt takes over projects you already have, and it checks the folder before it writes or moves anything. There is no stack it refuses; what it refuses is a folder it cannot safely take over. Each refusal names what it found:

• nothing to adopt. There is no project inside the folder you named, within three folders of it.
• too large to read. The walk stopped early, so torta cannot describe what is in there. Point it at one project instead.
• nobody could be worked out for anything in there. The reading came back with nothing usable. Say who owns each project with --as <owner>, or adopt them one at a time.
• two projects in one repository. An owner keeps one project per repository. Give one of them another owner, or leave it where it is.
• already a torta workspace, or a folder inside one. There is nothing left to adopt.
• your home folder, or the root of the disk. Adopting either would move everything you own into one project.

Nothing is written by a refusal. torta adopt <dir> --dry-run prints the whole plan without touching anything.

torta adopt moved my project and I want it back

torta adopt <dir> --undo

That is the command ADOPTED.md prints at the bottom of the folder torta adopted. It removes what torta wrote, puts back anything it moved aside, and reverses every move through the journal that recorded it. It refuses, naming the file, rather than remove something of torta’s you have edited since: move that file aside and ask again.

An adoption stopped part way

torta adopt <dir> --resume

Every rename is written down before it happens, so a move that was interrupted is finished from its own record rather than guessed at. Once it has finished, --undo still puts the folder back.

torta adopt started a Claude Code session

It did, and that is how it works now. Adoption reads the folder you named with one read-only Claude Code session on your own login, to answer the one question nothing on disk can: which agent owns each project in there. It reads files and runs nothing, no writes, no commands, no network, and both doors say it is happening while it works.

It is not asked for because torta refuses to run at all without Claude Code installed and signed in, so a second permission for one read-only session is friction for something you agreed to by installing it. Saying who owns every project yourself, with --as <owner> once per project, skips the reading entirely: there is nothing left to read for.

torta adopt left one of my folders where it was

The reading would not place it, so torta did not guess. An unplaced project is never moved, nothing is written inside it, and ADOPTED.md names it. Adopt it on its own once you have decided who owns it, or say so up front:

torta adopt <dir> --as frontend --as infra