CLI

noc is the short name. nocturnal is the long one. Both talk to the Nocturnal engine on this machine. Launch the app if nothing is listening.

Process verbs sit at the top so you can type noc ls instead of nocturnal proc ls.

Every engine command is reachable, whether or not it has a short verb below — see commands and cmd. To point an agent or an assistant at Nocturnal, start at Control Nocturnal from an agent.

status

noc status

Daemon health: version, device, uptime, how many projects it can see.

Processes

noc ls
noc start -p <projectId> -c "<command>" [--cwd <path>]
noc stop <id>
noc restart <id>
noc delete <id>
noc logs <id> -n 80
noc save
noc resurrect
noc start-group -p <projectId> -g <groupId>
noc stop-group -p <projectId> -g <groupId>
noc stop-all -p <projectId>

nocturnal proc … is the long form of the same verbs.

git

noc git status --cwd <path>
noc git commit --cwd <path> -m "message"
noc git branch <name> --cwd <path>
noc git checkout <name> --cwd <path>
noc git push [name] --cwd <path>
noc git merge <name> --cwd <path>
noc git pr -o <owner> -r <repo> -t "Title" --head <branch> --base main [--cwd <path>]
noc git publish -p <projectId> [-n <name>] [--public]

publish creates the GitHub repo (private unless --public) and pushes. Same as the Git tab Create repository card. pr pushes the head branch first, then opens the pull request.

Ports

noc ports rotate -p <projectId>
noc ports fix -p <projectId>
noc ports kill --port 3000

rotate moves this project's services onto free ports. fix only remaps clashes. Both prepare a remap you review in the dashboard.

agent

noc agent ls
noc agent new -p <projectId> --prompt "..."
noc agent continue -s <sessionId> --prompt "..."
noc agent loop -s <sessionId> --prompt "..." --times 15
noc agent loop -s <sessionId> --stop
noc agent stop -s <sessionId>
noc agent archive -s <sessionId> [--undo]
noc agent rename -s <sessionId> --title "Name"
noc agent fork -s <sessionId>

project

noc project ls
noc project create -n "My App" [--id my-app]
noc project import --path <folder>
noc project adopt --path <folder>
noc project rescan
noc project rename -p <projectId> -n "New name"
noc project link -p <projectId> -n "Staging" -u https://…
noc project archive -p <projectId> [--restore]

import registers a folder; adopt runs the deep scan that writes .nocturnal/project.json.

issue

noc issue ls -p <projectId> [-s open|closed|all]
noc issue show <number> --project-path <path>
noc issue create --project-path <path> -t "Title" [-b "body"] [-l bug,ui]
noc issue comment <number> --project-path <path> -b "text"
noc issue close <number> --project-path <path> [--reason not_planned]

plan

noc plan ls
noc plan create -p <projectId> --prompt "..." [--no-start]
noc plan build <planId> [--now]
noc plan status <planId> ready

settings

noc settings get
noc settings set agentDefaultModel claude-opus-5
noc settings set mirrorAgents true

topics

noc topics
noc topics projects
noc topics agentsIndex

Everything the dashboard renders, as JSON. Omit the name for all of it.

commands and cmd

noc commands                  # every command, grouped, with its parameters
noc commands git              # only the ones matching "git"
noc commands -g Agents        # one group
noc commands --markdown       # the full reference as markdown

noc cmd <command> key=value …
noc cmd agent.new projectId=my-app prompt="fix the header"
noc cmd proc.restart id=my-app-web
noc cmd issue.create projectPath=/repo title="Bug" labels=bug,ui
noc cmd agent.loop --json '{"sessionId":"s1","prompt":"tidy","times":3}'

cmd reaches every command the engine has, including any added after the verbs above. Values are converted using the command's declared types, and a missing required parameter is reported before anything is sent.

version

noc version -p <projectPath>

Starts a version cut for that repo.

script

noc script -p <projectId> -s <scriptId>
noc script-stop -p <projectId> -s <scriptId>

One-shot commands (deploy, seed, migrate). They do not restart when they exit.

engine

noc engine start

Starts the local engine if it is not already running.

CLI