nucleate commands
Every nucleate command, what it prints and how it fails. Each one prints JSON, so a script, the daemon or an agent can read the same answer you do.
nucleateOn this page
- How every command behaves
- Options shared by commands
- Setting up the nucleus
- nucleate init
- nucleate clone
- nucleate available
- nucleate refresh
- Working in a session
- nucleate create-session
- nucleate add
- nucleate status
- nucleate remove
- nucleate remove-session
- Signing a box in to Watch
- nucleate login
- nucleate whoami
- nucleate logout
- Exit codes
- Where the credential lives
- For the agent
- nucleate hook-create
- nucleate hook-remove
- nucleate mcp
How every command behaves #
- Output is JSON on standard output, indented, with keys in alphabetical order. The two hook commands are the exception; they print what Claude Code expects.
- A failure prints one line on standard error, starting
nucleate:, and exits with status 1. Nothing is printed on standard output. - Success exits 0.
nucleate refreshis the one command that can print its JSON and still exit 1. - Error tables on this page leave the
nucleate:prefix off each message. - When
gitfails, the line carries thegitcommand and whatgitsaid:
nucleate: git --git-dir /home/agent/workspace/.repos/web.git fetch -q origin +refs/heads/main:refs/remotes/origin/main failed: fatal: unable to access 'https://github.com/your-org/web.git/': Could not resolve host: github.com
Options shared by commands #
| Option | Applies to | Meaning |
|---|---|---|
--root <path> |
Every command | The nucleus to work in. Without it, the root comes from NUCLEATE_ROOT, the config file, or the nearest folder above you that contains .repos. See configuration. |
--session <name-or-path> |
add, status, remove |
The session to act on. Without it, the session is the one your current folder is inside. |
--version, --help |
Every command | Print the version, or the usage. |
--session takes a name (fix-login), an absolute path, or a relative path to a session folder. Whatever it resolves to must be inside the nucleus's .worktrees/ folder:
nucleate: session must be under /home/agent/workspace/.worktrees: /tmp/elsewhere
Without --session, running outside any session fails:
nucleate: not inside a workspace session under /home/agent/workspace/.worktrees
A repo argument is the repo's name (web) or its label (your-org/web). Both find the same clone.
Setting up the nucleus #
nucleate init #
nucleate init [--root <path>]
Creates .repos/, .worktrees/ and .seeds/ under the root and writes root to the config file. The root is --root if you give it, otherwise the folder you are in.
{
"config": "/home/agent/.config/nucleate/config.toml",
"created": true,
"root": "/home/agent/workspace"
}
Running it again on the same folder changes nothing and prints "created": false.
nucleate clone #
nucleate clone <url> [--name <name>]
Makes a repository available. It clones <url> bare to .repos/<name>.git, switches the clone to remote-tracking refs, fetches, and records the remote's default branch. Those are the four git commands shown under bare clones. The name is the last part of the URL unless you pass --name.
{
"bare": "/home/agent/workspace/.repos/web.git",
"label": "your-org/web",
"repo": "web"
}
The output is one entry in the shape nucleate available uses.
nucleate available #
nucleate available
Lists the repos that can be added to a session: every bare clone in .repos/, sorted by name. An empty nucleus prints [].
[
{
"bare": "/home/agent/workspace/.repos/api.git",
"label": "your-org/api",
"repo": "api"
},
{
"bare": "/home/agent/workspace/.repos/web.git",
"label": "your-org/web",
"repo": "web"
}
]
| Field | Meaning |
|---|---|
repo |
The short name: the clone's folder name without .git. |
label |
owner/name from the clone's GitHub remote, or the short name for any other remote. |
bare |
The path of the bare clone. |
nucleate refresh #
nucleate refresh
Fetches every bare clone, drops remote branches that were deleted upstream, and updates each clone's record of the default branch. Worktrees are not touched: a long-running session still has to git fetch and rebase for itself.
[
{
"ok": true,
"repo": "api"
},
{
"error": "fatal: unable to access 'https://github.com/your-org/web.git/': Could not resolve host: github.com",
"ok": false,
"repo": "web"
}
]
One repo failing does not stop the others. The exit status is 0 when every repo fetched and 1 when any did not, so a timer or a script can tell. error is present only on a failed entry and holds what git said.
Working in a session #
nucleate create-session #
nucleate create-session <name> [<repo>...]
Creates the session folder .worktrees/<name>/ with its manifest and AGENTS.md. Any repos you list are added straight away, on the session branch.
{
"path": "/home/agent/workspace/.worktrees/fix-login",
"session": "fix-login"
}
If one of the listed repos cannot be added, the whole session is undone: the worktrees already made are removed, the folder is deleted, and the command fails with the reason.
| Error | Why |
|---|---|
invalid session name: "bad name" |
The name breaks the name rules. |
session already exists: /home/agent/workspace/.worktrees/fix-login |
There is already a folder with that name. |
repo not available in /home/agent/workspace/.repos: docs |
A listed repo has no bare clone. |
nucleate add #
nucleate add <repo> [<branch>] [--session <name-or-path>]
Adds a repo to a session as a git worktree. It fetches first, so the worktree starts from what the remote has now. Without <branch> the repo goes on the session branch. With it, the repo goes on that branch: resumed if it exists locally or on the remote, created from the default branch if it does not. Seed files named by the repo's .worktreeinclude are copied in, the manifest is updated and AGENTS.md is rewritten.
{
"already_present": false,
"bare": "/home/agent/workspace/.repos/web.git",
"base": "15b80ae12bb3a17934cf98b293f75248c1b73e73",
"branch": "workspace/fix-login",
"label": "your-org/web",
"path": "/home/agent/workspace/.worktrees/fix-login/web",
"repo": "web"
}
| Field | Meaning |
|---|---|
repo, label, bare |
As in nucleate available. |
path |
The new worktree. |
branch |
The branch it is on. |
base |
The full commit id the worktree started at. |
already_present |
false when this call added the repo. |
Adding a repo the session already has is harmless. Nothing changes, and the answer is shorter:
{
"already_present": true,
"branch": "workspace/fix-login",
"path": "/home/agent/workspace/.worktrees/fix-login/web",
"repo": "web"
}
| Error | Why |
|---|---|
repo not available in /home/agent/workspace/.repos: docs |
No bare clone by that name or label. |
invalid repo name: "a b" |
The name could never be a repo. |
invalid branch: "bad branch" |
The branch breaks the name rules. |
/home/agent/workspace/.worktrees/fix-login/web already exists but is not in the manifest |
Something else made that folder. Move it away and add again. |
A branch can be checked out in one worktree at a time. Adding a repo on a branch that another session holds fails with git's own message naming the other worktree.
nucleate status #
nucleate status [--session <name-or-path>]
Shows a session: its branch, each repo in it, what is unsaved in each, and what else could be added.
{
"available": [
{
"bare": "/home/agent/workspace/.repos/api.git",
"label": "your-org/api",
"repo": "api"
},
{
"bare": "/home/agent/workspace/.repos/web.git",
"label": "your-org/web",
"repo": "web"
}
],
"branch": "workspace/fix-login",
"path": "/home/agent/workspace/.worktrees/fix-login",
"repos": {
"web": {
"bare": "/home/agent/workspace/.repos/web.git",
"base": "15b80ae12bb3a17934cf98b293f75248c1b73e73",
"branch": "workspace/fix-login",
"dirty": true,
"head": "8c71984",
"label": "your-org/web",
"path": "/home/agent/workspace/.worktrees/fix-login/web",
"unsafe_reasons": [
"uncommitted changes",
"1 unpushed commit(s)"
]
}
},
"session": "fix-login"
}
| Field | Meaning |
|---|---|
session, path, branch |
The session's name, folder and session branch. |
available |
Every repo in the nucleus, in the shape nucleate available prints. |
repos |
One entry per repo in the session, keyed by repo name. Empty ({}) for a new session. |
repos.*.dirty |
true when the worktree has uncommitted or untracked changes. |
repos.*.head |
The short id of the commit the worktree is on. |
repos.*.unsafe_reasons |
Why this worktree would not be removed. Empty when it is safe to remove. The strings are listed under the safety rule. |
The remaining fields of each repo (label, bare, path, branch, base) are the manifest's.
If a worktree's folder has gone missing, its entry says so in place of the three live fields:
{
"bare": "/home/agent/workspace/.repos/web.git",
"base": "15b80ae12bb3a17934cf98b293f75248c1b73e73",
"branch": "workspace/fix-login",
"label": "your-org/web",
"missing": true,
"path": "/home/agent/workspace/.worktrees/fix-login/web"
}
status always exits 0 for a real session, whatever it finds. Read unsafe_reasons, not the exit status.
nucleate remove #
nucleate remove <repo> [--force] [--session <name-or-path>]
Removes one repo from a session. It refuses if the worktree holds unsaved work, and says what:
nucleate: web: uncommitted changes; 1 unpushed commit(s)
On success the worktree is removed, the repo leaves the manifest and AGENTS.md, and the local branch is deleted if its commits are stored elsewhere.
{
"removed": "web",
"session": "/home/agent/workspace/.worktrees/fix-login"
}
--force removes the worktree whatever it holds. Uncommitted and untracked files in it are gone for good. Commits are not: the local branch is deleted only when its tip is on a remote branch or was merged, so forced-away commits stay on the branch in the bare clone. See what force discards.
| Error | Why |
|---|---|
web: uncommitted changes |
Unsaved work, with every reason joined by ; . |
repo not in session: web |
The session does not hold that repo. |
repo not available in /home/agent/workspace/.repos: docs |
No bare clone by that name. |
nucleate remove-session #
nucleate remove-session [<name-or-path>]
Removes a whole session: every worktree, the local branches whose commits are stored elsewhere, and the folder. The session is a plain argument here, not --session; leave it out to remove the session you are standing in.
It is all or nothing. Every repo is checked before anything is removed, and one repo with unsaved work keeps the whole session:
nucleate: refusing to remove session with unsaved work: api: 2 unpushed commit(s) | web: uncommitted changes
Repos are separated by |, and each repo's reasons by ; . There is no --force for a session: deal with each named repo, or force them out one at a time with nucleate remove.
{
"removed_session": "/home/agent/workspace/.worktrees/fix-login"
}
Signing a box in to Watch #
These three commands are the only ones that talk to Nucarium Watch. None of them is needed to use nucleate by itself. Connect a box walks through the first sign-in.
nucleate login #
nucleate login
Signs this box in. A box has no browser, so it prints a short code and the address https://app.nucarium.com/activate, then waits while you enter the code on your phone or laptop, choose the machine or name a new one, and approve. This is the OAuth 2.0 device flow. The code lasts 15 minutes.
Everything meant for a person goes to standard error. When you approve, standard output gets:
{
"account_name": "Your Org",
"api_url": "https://api.nucarium.com",
"logged_in": true,
"machine_id": "mac_7h2k9m4q1x8z5b6n",
"machine_name": "agentbox",
"replaced": false,
"scope": "ingest",
"token_file": "/home/agent/.config/nucleated/token"
}
The token is a machine token: it can report on this one machine and can read nothing. It is stored in token_file, readable by the agent user only, and no command prints it. It does not expire. Signing in again rotates it: the new token is stored, the one it replaces is revoked, and the output says "replaced": true.
| Flag | Meaning |
|---|---|
--name <name> |
The machine name to suggest. Default: machine from the daemon's config, or the hostname. You can change it when you approve. |
--token-stdin |
Store a token minted in the console, read from standard input, without the sign-in. For setting up a box with nobody present. It does not contact Watch. |
--api-url <url> |
For people developing Nucarium against an API on the same machine. |
printf '%s' "$TOKEN" | nucleate login --token-stdin
nucleate whoami #
nucleate whoami
Prints which machine and account this box is signed in as, and whether Watch still accepts its token. It changes nothing in Watch and sends no heartbeat, so a box whose daemon has stopped still looks stopped.
{
"account_name": "Your Org",
"api_url": "https://api.nucarium.com",
"logged_in": true,
"logged_in_at": "2026-11-19T02:40:12.000Z",
"machine_id": "mac_7h2k9m4q1x8z5b6n",
"machine_name": "agentbox",
"scope": "ingest",
"token": "valid",
"token_file": "/home/agent/.config/nucleated/token"
}
token is "valid", "rejected", or "unknown" when Watch cannot be reached to ask. On a box that is not signed in it prints "logged_in": false and the token file's path, says so on standard error, and exits 5.
nucleate logout #
nucleate logout
Revokes the token at Watch, then deletes it from the box. If Watch cannot be reached the token is still deleted, the output says "revoked": false, and a line on standard error tells you to revoke it in the console.
{
"api_url": "https://api.nucarium.com",
"logged_out": true,
"revoked": true,
"token_file": "/home/agent/.config/nucleated/token"
}
On a box that was not signed in it prints "logged_out": false with "reason": "not_logged_in", and still exits 0.
Exit codes #
| Code | Meaning |
|---|---|
| 0 | Done. For logout this includes a box that was not signed in, and a token that is gone from the box though Watch could not be told. |
| 1 | Something failed: Watch could not be reached or answered unexpectedly, or a file could not be written. |
| 2 | The command line was wrong. |
| 3 | login: you denied the request in the console. |
| 4 | login: the code expired before anyone approved it. |
| 5 | whoami: this box is not signed in. |
| 6 | whoami: Watch rejected the stored token. |
| 130 | login: cancelled with Ctrl+C. Nothing was stored. |
Where the credential lives #
| File | Mode | Holds |
|---|---|---|
~/.config/nucleated/token |
600 | The machine token and nothing else. |
~/.config/nucleated/login.json |
600 | No secret: the API address, the machine's id and name, the account's name, and when the box signed in. |
Neither nucleate nor nucleated uses a token file that its group or anyone else can read. They say so and behave as if the box were not signed in.
For the agent #
These three are not typed by hand. Claude Code hooks and the MCP server shows how they are registered.
nucleate hook-create #
nucleate hook-create [<repo>...]
The WorktreeCreate hook. It reads the hook's JSON event on standard input and uses two fields: name and cwd. It creates a session called name, with any repos you listed already added, and prints the new folder's path. That path, alone on one line, is the only thing it prints, because Claude Code takes the hook's output as the place to start the session.
/home/agent/workspace/.worktrees/fix-login
If cwd is already inside a session, it makes a sub-worktree of the repo at cwd instead, and prints that path.
| Error | Why |
|---|---|
parsing the hook payload on stdin: ... |
Standard input was not JSON. |
hook payload has no name |
The event carried no name. |
invalid session name: ..., session already exists: ... |
As for create-session. |
nucleate hook-remove #
nucleate hook-remove
The WorktreeRemove hook. It reads the event on standard input and uses one field, worktree_path. If that path is a session, it does what remove-session does. If it is a single worktree, it applies the same unsaved-work check to that worktree and removes it.
It prints nothing. Exit status 0 means the folder is gone. Exit status 1 means it was left alone, with the reason on standard error:
nucleate: refusing to remove session with unsaved work: web: uncommitted changes
nucleate mcp #
nucleate mcp
Runs a Model Context Protocol server on standard input and output, one JSON message per line, until its input closes. It offers four tools, list_repos, add_repo, remove_repo and workspace_status, which act on the session the server's working folder is inside. The tools are described with the rest of the agent integration.