Set up a Development Root

Nexa expects one folder on your machine to hold everything you are actively working on. That folder is your Development Root, and you declare it once with nexa root.

Prerequisites

nexa installed and on your PATH — see Install the Nexa CLI.
Signed in with nexa login if you will publish to Rinko Hub — see Authorize your machine. Local-only work does not need it.
A folder you are happy to keep your projects in. It may be empty or already contain work. The examples call it ~/Development.

What you'll do

Declare one directory as your Development Root, and understand what that did.

What a Development Root is

A Development Root is a single directory that holds your active work, with each project in its own subdirectory beneath it. Those subdirectories are working contexts: one repository, at one branch and one workspace, materialized as ordinary files you can edit. A repository is one project's object database and history; a branch holds a set of competing candidates; a workspace is a context inside a branch in which several attempts at the same problem can coexist.

A project directory becomes a working context in one of two ways, both run at the root. nexa init my-project (or nexa init -p my-project, which works from anywhere in the root) makes a folder a project, creating it if needed — that is the next page. nexa get brings in a repository that already exists on Rinko Hub or elsewhere on your disk. In both cases the root keeps track of which directory is which, and later commands name a project with -p rather than needing you to change into it.

The model on disk

~/Development/        ← the Development Root
├── .nexa/            ← control state for every project beneath it
├── .nexapolicy       ← file-handling rules, one project block per project
├── my-project/       ← a working context: your files, and nothing else
└── another/          ← another working context, independent of the first

Only the root carries a .nexa/ directory. The project directories underneath it are plain working trees — the control state that says what each one is belongs to the root, not to them.

Your project folders stay yours

Nexa writes nothing inside a project directory. Everything it needs — control state and your file-handling policy — lives at the root, so a project folder contains your files and nothing else. If you list one and find no trace of Nexa, that is the correct result, not a sign that something failed to set up.

A root holds many repositories; it is not one

~/Development/.nexa is control state for many independent projects. It is not a repository, and declaring a root does not put every folder beneath it into one shared history. Each project you init is its own repository, recorded and published on its own, and a sibling directory you never init is simply not managed at all.

`root` is not `init`

nexa root nominates a folder as the place your projects live. nexa init makes one folder inside it a project. Outside any Development Root, nexa init still creates a standalone repository with its own .nexa/.

Declare the root

Change into the folder you want to use, and run:

Command

$ cd ~/Development

Command

$ nexa root

Expected output

Development Root: ~/Development

With no argument it uses the current directory. Naming one explicitly does the same thing for that path:

Command

$ nexa root ~/Development

What happens

The command creates a .nexa/ directory inside the folder, records it as a Development Root, and prints the absolute path it registered. It exits successfully. Nothing else in the directory is read, moved, or modified — declaring a root over a folder that already has projects in it leaves those files exactly as they were, and makes none of them managed until you init them.

Running it twice is safe

nexa root is idempotent. Running it again on a directory that is already a Development Root re-registers the same path, prints the same line, exits successfully, and leaves any working contexts already recorded there intact. There is no error to avoid and no state to clean up first.

Working on a project from the root

Standing at the Development Root, name the project with -p (short for --project):

Working from the root

cd ~/Development
nexa status -p my-project
nexa record -p my-project -m "What changed, and why"
nexa record -p my-project src/main.rs -m "Just this file"
nexa sync -p my-project

-p names the project by its folder in the root, which is also what makes the third line above unambiguous: my-project is the project and src/main.rs is the path. nexa my-project status is an accepted shorthand for the same thing.

There are three ways to say which project, and they match how you already work:

Where you are	What you type	Which project
The Development Root	`nexa status -p my-project`	the one you named
The Development Root	`nexa status`	you are asked to choose
Inside `my-project/`	`nexa status`	worked out for you

Inside a project, nothing needs naming — exactly as before. At the root with no project named, Nexa asks which one you mean. In a script, in CI, or under --format json it will not stop to ask — it fails and lists the projects, so an unattended run reports a problem instead of hanging forever.

When a project shares a command's name

In the nexa <project> <command> shorthand, a command name always wins. If you have a project called status, then nexa status still means the command. -p always names the project unambiguously:

Code

nexa status --project status   # the project called "status"
nexa status                    # the command

-p (or --project) works on every command that acts on a project. Commands that have no project, such as nexa login and nexa update, do not take it.

What changed on disk

Two things, both at the root. A new .nexa/ directory, in which Nexa keeps a record of the root's own format and an entry for each working context — which repository it belongs to, and which branch and workspace it shows. That record is how nexa contexts can list your work, and how a command run inside a project directory knows which repository it belongs to without the project carrying any metadata of its own.

And a starter .nexapolicy, the one file you edit to say how paths are handled — which are encrypted, and under which label. One physical file sits at the root, and each project is named inside it in a project "my-project" { … } block rather than given a policy file of its own. The starter declares nothing: it is comments showing that shape. If a .nexapolicy is already there, nexa root leaves it exactly as it is.

One file, but rules per project

The file is shared; the rules in it are not. A label belongs to one project's repository, so a rule naming a label lives in that project's block. A label rule written outside any project block — in global — is refused, because each project would resolve it against its own, unrelated labels. Protect private files before hosting walks through writing the rules.

Your existing files are untouched. No repository was created, nothing was recorded, and no network request was made — nexa root is an entirely local operation.

Expected result

The folder now contains a .nexa/ directory and a .nexapolicy file, and nexa contexts — run at the Development Root itself — reports that it holds no working contexts yet. That is the correct state for a root you have just created.

Next step

Create a project: your first repository. Its private files are protected on the page after that, before anything is recorded or published. If you only intend to work on local repositories, stop before nexa publish.