The toolchain

One binary does everything: running, checking, building, testing, formatting and documenting. These pages say which command, which flag and which file.

torb is the binary the installer puts on the PATH, and a command on these pages runs in the directory of a project - the one with project.trb - unless it names a path.

What belongs here#

The commands of the toolchain, their flags and their exit codes; the project files (project.trb, project.lock.trb); and the formatter canon as the toolchain enforces it.

What does not belong here: the language itself, which is the reference, and the compiler's own design, which is in internals. A page here is about what you type and what comes back.

Pages#

• The torb command - Every subcommand of the toolchain, what it does today, and which of them are still planned.
• Verify your work - The commands that decide whether TorbScript you wrote is correct and in the layout of the formatter, in the order to run them.
• torb new - torb new scaffolds a package or app from a template - git.torb.dev's package or app by default - or, offline, the built-in project.trb, src/main.trb and tests/main.test.trb; torb init does the same into the current directory.
• torb init - torb init fills the current, empty-enough directory with a template - or the built-in scaffold - the way torb new fills a new one, and refuses to overwrite a file that is already there.
• torb check - torb check resolves every module, import and name in a type position, types every expression, and reports one block per diagnostic - the gate every other command trusts.
• torb run - torb run runs a file, the only program below a directory or the program named in the bytecode VM, or builds and runs it natively with --native, passing the rest of the command line, the three streams and the exit code through.
• torb repl - torb repl reads entries from standard input, checks each against the session, runs it in the bytecode VM and keeps what it binds and declares for the next entry - a typed session and a piped file behave the same.
• torb lsp - torb lsp is the language server - the compiler over the Language Server Protocol - with the diagnostics of torb check for the whole workspace, hover from torb doc, references, a checked rename, completion, formatting and lint fixes.
• The playground - The playground at torb.dev/play and in the course runs TorbScript in the browser - torb as WebAssembly runs the program in its VM and its language server completes and checks as you type, with no server - and what a program can do there.
• torb debug - torb debug is the debugger - a debug adapter over the Debug Adapter Protocol on standard input and output - with breakpoints, stepping, the call stack, locals and evaluate for a program or a test run in the VM.
• torb build - torb build type checks every program below a path, or the one named, lowers each to C and hands the C to whatever compiler it finds - a library is checked and builds nothing.
• torb test - torb test runs every *.test.trb file below the paths it is given - one binary for all of them - and prints ok or FAILED for every test call it sees, or JSON Lines for an editor, of every test or of the ones a filter names.
• torb canon - torb canon is deprecated - it runs torb format now, with a warning - and the formatter canon it enforced, every rule of it, is what torb format runs first, over the syntax tree and with a safety net.
• torb docs source - torb docs source checks the doc comments of the code itself - a module comment on every file, a comment on every construct that needs one, six headings, links that resolve, and examples that compile.
• torb docs site - torb docs site writes the website of TorbScript from docs/ as static files - three levels from the first lesson to the reference and a project area apart from them, in every language of translations/, with a search per language.
• project.trb - The manifest of a project - its name, dependencies, workspace, further programs and profiles. The names of its files say what it produces, and the settings that decide its files are read before anything runs.
• project.lock.trb - The locked manifest - the exact version, tree hash and registry of every package a workspace depends on, and the evaluated settings of each of its packages - written deterministically and read without running anything.
• torb add - torb add writes a dependency into project.trb, resolves the workspace with it, writes project.lock.trb and installs what is new - or changes nothing and explains why there is no solution.
• torb remove - torb remove takes a dependency out of project.trb, resolves the workspace again, and drops from project.lock.trb every package nothing needs any more.
• torb update - torb update resolves every package of the workspace, or only the named ones, to the highest version project.trb allows, writes project.lock.trb, and refuses an update that gains a capability unless --accept-capabilities says it is wanted.
• Package capabilities - Which std modules a package's imports reach, as the capability each one is - files, network, processes, clock and the rest - and how the registry shows the set of every version and flags a gain.
• torb install - torb install fetches every package project.lock.trb pins that is not in the cache yet, checks its tree hash before a file is written, and never changes the lock.
• torb publish - torb publish builds and checks a package's archive as a registry receives it, prints its tree hash and capabilities, and writes it into a directory registry or uploads it with a token or through trusted publishing.
• torb lock - torb lock writes the settings block of every member of a workspace into project.lock.trb from its evaluated manifest and keeps the graph as it is; with --check it writes nothing and fails where the file is not what it would write.
• torb vendor - torb vendor copies every registry package project.lock.trb pins into vendor/ after checking its tree hash, names each copy with a source path line and locks it as a path package, so a build needs neither the cache nor a network.
• config.trb - The user's own configuration of the package manager, ~/.torb/config.trb or $TORB_CONFIG - mirror lines that change where the files of a registry on the network are fetched from, and never what is resolved, trusted or locked.
• torb audit - torb audit checks every registry package project.lock.trb pins against its registry index - a yanked version, a deprecated package - and with --advisories against advisory files; it changes nothing and exits 1 on a finding.
• torb deprecate - torb deprecate flags a whole package as deprecated, with a package to use instead and a reason that torb add prints; --undo takes the flag back. Nothing is withdrawn, and a file registry gets the line appended to its index.
• torb login - torb login reads a token of a registry from standard input, asks the registry whether it holds, and stores it in the user's credentials.trb, where torb publish and the other commands that speak to the registry find it.
• torb logout - torb logout removes the token torb login stored for a registry from the user's credentials.trb, and says so where there was none.
• torb owner - torb owner lists an owner on a registry - its kind, proved domain, elsewhere registry and members - and adds, changes or removes a member, proving the account's second factor with a code or a passkey's step-up.
• torb yank - torb yank withdraws a published version from new resolutions with a reason a lock that pins it prints, and torb yank --undo takes the yank back; on a file registry it appends the line to the index itself.
• torb doc - torb doc turns the public API of a package and its doc comments into a reference - a static site, or one JSON document for an editor and the registry - and runs the examples of the doc comments as doc tests.
• torb format - torb format writes TorbScript sources in the one layout of the language - the rules of the formatter canon, then indentation, spaces, blank lines and a width of 120 columns - and --check fails on every file that is not in it.
• torb lint - torb lint reports the style rules the type checker leaves alone - Self, a question field, an unread binding, an unlabeled literal, a redundant Some or closure, private(var) - and uses of deprecated declarations, with a fix where certain.
• torb rename - torb rename renames fields at their declaration and at every use the type checker resolves to them - members, bare names, labels, patterns and doc links - or refuses and writes nothing.