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.

On this page

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 refresh is 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 git fails, the line carries the git command and what git said:
Output
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:

Output
nucleate: session must be under /home/agent/workspace/.worktrees: /tmp/elsewhere

Without --session, running outside any session fails:

Output
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 #

Usage
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.

Output
{
  "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 #

Usage
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.

Output
{
  "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 #

Usage
nucleate available

Lists the repos that can be added to a session: every bare clone in .repos/, sorted by name. An empty nucleus prints [].

Output
[
  {
    "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 #

Usage
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.

Output
[
  {
    "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 #

Usage
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.

Output
{
  "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 #

Usage
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.

Output
{
  "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:

Output, when the repo was already there
{
  "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 #

Usage
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.

Output
{
  "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:

Output, a repo whose folder was deleted by hand
{
  "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 #

Usage
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:

Output
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.

Output
{
  "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 #

Usage
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:

Output
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.

Output
{
  "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 #

Boxas agent
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:

Output
{
  "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.
Boxas agent
printf '%s' "$TOKEN" | nucleate login --token-stdin

nucleate whoami #

Boxas agent
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.

Output
{
  "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 #

Boxas agent
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.

Output
{
  "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 #

Usage
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.

Output
/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 #

Usage
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:

Output
nucleate: refusing to remove session with unsaved work: web: uncommitted changes

nucleate mcp #

Usage
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.