Create your first repository

mkdir myproject

cd myproject

tovio init

tovio init initialises the current directory and accepts no path argument. tovio init myproject is rejected with error: unexpected argument 'myproject' found — make the directory first.

Run interactively with no flag, init asks one question: ? Who will be working on this repository?, with three numbered answers and 1) Just me as the default. In a non-interactive shell — a script, a CI job, a pipeline, or any run under --json or --quiet — it does not hang waiting: it chooses simple silently. If a script needs a different mode, pass it explicitly:

tovio init --mode simple

tovio init --mode team

tovio init --mode agentic

The three modes

team and agentic need a reachable keychain

Both provision a brand-new identity: the secret is sealed on disk at .tovio/identity/default.key, and the 32-byte key that unseals it goes into the OS keychain. If the keychain is locked or unreachable, init fails with TVO-KEY-002 — retitled for this surface as "Could not create a repository identity", exit class 11.

It rolls back the half-built .tovio it had started, so the directory is left exactly as it was and your retry is never blocked by TVO-CLI-004. Unlock the keychain and re-run, drop to --mode simple, or inject a wrapping key through TOVIO_KEYSTORE_KEY — see the headless-host article.

What init creates

A single .tovio/ directory. Your working files are ordinary files and nothing about them changes. Inside it:

The starting lane is main, and you are already inside a change before you have typed a single command — that is what the chg: id in the init output is.

Going from Simple to Team later

You are not locked in. From inside an existing Simple repository:

tovio identity init

That provisions a cryptographic identity and upgrades the repository to Team. It is a real cryptographic operation, not a flag flip — but be clear about what it does and does not touch: existing public history is not re-encrypted. Only paths that newly match a policy get sealed, and only in the commits you make after the upgrade. If you need earlier content protected, that is a separate, deliberate exercise.

There is no tovio policy promote. tovio identity init is the upgrade path.

Next

Run tovio quickstart for a guided tour in a throwaway repository, or just start editing files here and run tovio status.