Dictate a prompt (interactive terminal)

Install a microphone recorder on PATH before enabling voice: winget install ffmpeg on Windows, brew install ffmpeg on macOS, or your distribution's ffmpeg package on Linux. Linux can also use pw-record or arecord when available. Restart the terminal after installation if its PATH has not updated. Then log in to Compass and run /voice on inside Nova. /voice status shows the active recorder; /voice off disables dictation for this session.

The first use asks you to acknowledge that audio is sent to Compass for OpenAI Whisper transcription using your organisation's configured key. Nova deletes the temporary local WAV after capture, never submits the resulting text automatically, and remembers your acknowledgement (not the on/off setting) in user-global configuration. Your organisation must have an OpenAI key configured. Voice input is unavailable in print mode, piped sessions, SDK/ACP, daemon, and AG-UI clients.

Tap Ctrl+Space or Alt+V to start recording; tap again to stop and insert the transcript at the cursor. Esc cancels a recording. If an agent turn is in progress, the transcript is queued until the prompt is ready; Esc discards queued text. Review the draft and press Enter yourself. Some terminals intercept Ctrl+Space; use Alt+V instead (macOS Terminal/iTerm2 may require Option as Meta). In config.json, voice.keybindings can choose either or both bindings. Silent or very short clips are discarded without upload. Recording stops after 120 seconds; transcription is not live.

Dictation uses the session's response language, or English before the first substantive request. To dictate in a different language, use /voice language pt-PT; /voice language default restores the session language. voice.windowsDevice, voice.linuxInput, and voice.silenceThresholdDb are optional user-global recorder/silence preferences. No recorder is downloaded by v1.

Isolate a change

nova --worktree

Start in a managed Git worktree and use nova worktrees to inspect or manage it. Merging or discarding isolated work is a separate action, not a side effect of starting a session.

To compile and try the Nova CLI from that worktree, open a separate PowerShell terminal and run:

Set-Location -LiteralPath '<worktree path shown by nova worktrees>'
npm ci
npm run build
npm start

npm start runs that worktree's compiled dist/cli.js, not an installed nova command. After editing source files, stop the running CLI, rebuild with npm run build, and start it again with npm start. The build writes to dist in the worktree, leaving the original checkout's build alone.

Use Nova in scripts

nova --print "Summarise the staged diff. Do not modify files or create a commit."
nova --model gpt-5.6-luna --print "Inspect this workspace and suggest the next step."

Print mode runs a single non-interactive query and writes only the completed final answer to stdout. SDK streaming callbacks and the legacy accumulated content result remain available to embedded clients; finalText contains the completed answer. Failed runs do not print partial answers.

For a self-contained writing task, opt into a single text completion. Supply the full source material in the prompt; this path does not read the repository, load conversation history, or expose tools. A concrete model is required.

nova --completion --model gpt-5.6-luna --system 'Return only a conventional commit message.' --max-tokens 120 --print 'Describe this supplied diff: ...'

Embedded clients can call runSDKCompletion({ prompt, model, system, maxTokens, abortSignal }). The result contains text, token usage, cost, stop reason, and preparation/provider/total timings. The CLI writes only the completed text to stdout. --completion rejects session, agent, attachment, and tool options; --system and --max-tokens apply only to completion mode. Existing SDK hosts may pass --unleash; completion mode accepts it for compatibility and ignores it because this path has no tools or approval flow.

--model <model> selects a model ID or alias for the print invocation while retaining Nova's normal system prompt. It overrides agent and resumed-session model preferences without changing the saved default. Backend routing and failover still apply; --model auto requests automatic routing.

nova --print 'Return only JSON describing this project. Do not modify files.' --validate-json --progress

--validate-json validates the entire final answer before emitting stdout; invalid or empty JSON fails with a nonzero exit and a stderr diagnostic. It does not force the model to generate JSON, remove Markdown fences, or validate a schema. --progress adds labelled status updates to stderr. --reasoning-summary adds only explicit provider-supported public summaries to stderr (currently OpenAI Responses); unavailable summaries produce no output, and raw thinking is never substituted. Tool diagnostics are silent by default; --tool-output compact or --tool-output verbose enables them on stderr. Print output also removes provider reasoning prefixes marked with <think>, <thinking>, or <reasoning>, including a missing opening tag when a closing tag identifies the prefix.

For integration clients, nova tools-rpc exposes an internal JSON-RPC stdio tool server; use nova tools-rpc --help for its explicit tool allowlist options. Interactive plan-lifecycle tools are not available in print mode.

Let sessions talk to each other

In interactive terminals, use /tag backend to name a peer session, then ask another session: Ask @backend about progress. Type @ to select a live peer; full IDs, unique eight-character ID prefixes, and quoted names such as @"Backend API" also work. A resolved mention turns on peer messaging for the current session until /peers refuse or exit. Unknown or ambiguous mentions show an error. @ no longer autocompletes or implicitly includes files; use ordinary paths or explicit attachments instead.

Make a workflow repeatable

Create .nova/commands/review.md in your project, using .compass/commands/review.md instead if that legacy directory is active:

---
description: Review the current diff
---

Review the current diff for correctness, regressions, and missing tests.
Read the surrounding code. Report actionable findings with file references.
Do not modify files, stage changes, or create a commit.

Then run /review inside Nova. Personal commands belong in the active ~/.nova/commands or ~/.compass/commands directory.

Visibility without leaving your workflow

Enable live events before starting a session. In PowerShell:

$env:NOVA_OBSERVABILITY = "1"
nova

In another terminal, from the same project:

nova dashboard

Nova opens the local live dashboard and prints its address, continuity-view address, and event-file location. Use nova doctor for diagnostic health checks; repairs are separate, confirmation-gated actions.

Inside a session: /help, /model, /plan, /agents, /mcp, /context, /compact, /tokens, /usage, /ask, /export, and /exit.

Nova loads project instructions from AGENTS.md, falling back to NOVA.md when AGENTS.md is absent. The same selection applies independently in the active project and global state directories (.nova or legacy .compass). If both files exist in one location, only AGENTS.md is loaded, even if empty; merging or deleting NOVA.md is up to you. Personal NOVA.local.md and state-directory rules/*.md continue to load as before. Automatic discovery covers these locations, not nested subdirectories.