Create your first repository

tovio init, the three collaboration modes, what lands on disk, and how to move from Simple to Team later.

Written By Dustin

Last updated 28 minutes ago

mkdir myprojectcd myprojecttovio 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 simpletovio init --mode teamtovio init --mode agentic

The three modes

ModePrompt textWhat it sets up
simpleJust me — keys auto-managedTier 0 Solo. No Key Authority, no policies, no identity ceremony, no keychain requirement. Local version control that just works. Start here unless you know you need more.
teamMe + teammates — a shared Key AuthorityTier 1. Provisions a cryptographic identity and the permission machinery, so you can write policies and grant access.
agenticMy team + AI agents — capability tokensTier 1/2. Team plus the agent surface, for repositories where AI agents will be issued capability tokens.

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:

EntryHolds
formatThe on-disk format marker, currently tovio-format 1.
config.tomlRepository configuration written by init — the mode, and the ref-tombstone settings.
actorThis repository's local actor id, a did:key: value.
objects/The content-addressed object store.
op-log/The local operation log that powers tovio undo and tovio redo.
refs/Lane and tag refs.
working-copy/HEAD, the current change, the hybrid-logical-clock watermark, and the stat-cache index.

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.