PromptWorks/lights-out/references/cli.md

Nightshift CLI reference

This file is a cache, not the source of truth. Verify with nightshift --help before relying on a flag; the roster and options change between releases. Captured against the maintained local fork 0.1.51-lights-out, based on upstream 0.1.49, commit 0227fe415d38e6df0fad4828c7999ba2a3b065de, plus local Nightshift changes. Usage analytics are removed at source level, not merely disabled. This is not an unmodified upstream artifact; required notices remain in LICENSE.

Normally you should not call nightshift directly — use scripts\start-run.ps1, which adds the preflight checks and the guaranteed finalize step. This reference exists for reading the flags the wrapper passes and for diagnosing a run.

Packaging

The skill vendors its own copy. There is no runtime install step and no dependency on an unrelated published package:

• engine bundle: vendor\node_modules\nightshift\dist\cli.mjs
• package metadata: vendor\node_modules\nightshift\package.json
• separately stored source: D:\OneDrive - Microsoft\HERE\nightshift-src.zip
• separately stored installer: D:\OneDrive - Microsoft\HERE\nightshift-0.1.51-lights-out.tgz

Neither archive is needed for normal runs or included when sharing the skill folder. Keep the preinstalled runtime modules and launchers in the shared copy. Vendor npm metadata refers to the external installer for maintenance only; recipients need their own installer path if reinstalling, not when running the existing copy.

Resolution order is $env:LIGHTS_OUT_NIGHTSHIFT → vendored copy → nightshift on PATH.

Only node needs to be on PATH. The .bin launchers stay beside the vendored package; the wrapper invokes the bundle through node.

Nightshift keeps its engine-owned repo state under .nightshift\runs\<runId>\ and its user config under ~\.nightshift\config.yml.

Flags

Flag	Notes
--agent <agent>	claude, codex, rovodev, opencode, copilot, pi, cursor, or acp:<target-or-command>
--model <model>	Overrides agentModel.<agent> from config
--max-iterations <n>	Abort after N iterations
--max-tokens <n>	Abort after N total input+output+cache tokens
--max-rate-limit-wait <dur>	Abort after this much cumulative usage-limit wait (30m, 2h, 0)
--fallback-model <model>	Retry a Claude usage-limit rejection with this model instead of waiting
--stop-when <condition>	Natural-language completion condition; survives resume. "" clears it
--prevent-sleep <on|off>	Keep the machine awake. The wrapper always sets on for overnight runs
--worktree	Run in a separate git worktree, enabling parallel runs on one repo
--current-branch	Commit on the current branch instead of creating nightshift/<runId>
--push	Push after each successful iteration
--meteor-frequency <0-5>	TUI meteors. The wrapper sets 0 because there is no interactive console
--mock	TUI demo only. Replays canned iterations, does no git work, does not exit. Never use it to validate a real run

Run identity

Deterministic, derived from the prompt:

slug   = prompt.toLowerCase()
           .replace(/[^a-z0-9]+/g,'-')
           .replace(/^-+|-+$/g,'')
           .slice(0,20)
           .replace(/-+$/,'')
hash   = sha256(prompt).hex.slice(0,6)
runId  = "<slug>-<hash>"
branch = "nightshift/<runId>"

On collision the engine appends -1, -2, …, so the predicted id may not be the final one. Resolve-LightsOutRunDir in scripts\lib.ps1 handles that.

Artifacts

Per run, in <repo>\.nightshift\runs\<runId>\:

File	Contents
prompt.md	The objective as given
notes.md	The agent's own iteration log — claims, not evidence
end-state.json	status, stopCondition, agentError, iterations, successCount, failCount, endedAt
nightshift.log	JSONL lifecycle log with timings and full error.cause chains
iteration-<n>.jsonl	Raw agent stream per iteration. Large; never copied to the vault
base-commit	Commit the run branched from
stop-when	Persisted stop condition

Behaviors that break unattended runs

Both are enforced by the wrapper's preflight:

1. Launching from a nightshift/* branch prompts interactively to overwrite or continue, and hard-fails when stdin is not a TTY.
2. An empty prompt with a non-TTY stdin makes the engine read the prompt from stdin and block forever.

Also: the engine requires a clean working tree, never force-pushes, never auto-pulls, and commits each successful iteration separately so a night can be reviewed or reverted one change at a time.

Provenance

The maintained source archive is stored separately at D:\OneDrive - Microsoft\HERE\nightshift-src.zip. Rebuild the vendored bundle from that fork when intentionally updating the engine; do not add a runtime install instruction to this skill.