claude-p

claude -p Skill

A reference for using claude -p (non-interactive print mode) to run Claude Code sessions programmatically — particularly for multi-turn conversations in server-side code.

This is the direct CLI approach, not the Claude Agent SDK. The key binary is claude, authenticated via claude auth login (subscription auth).

---

Core invocation

claude -p "your prompt" \
  --output-format stream-json \
  --verbose \
  --permission-mode acceptEdits \
  --model sonnet \
  --session-id <uuid>     # first turn only — see below

--output-format stream-json --verbose is required together: stream-json alone is rejected in -p mode without --verbose.

Auth: subscription, not API key

const env = { ...process.env };
delete env.ANTHROPIC_API_KEY;      // forces subscription auth
delete env.ANTHROPIC_AUTH_TOKEN;   // forces subscription auth
// Claude reads <CLAUDE_HOME>/ credentials automatically

Check auth status:

claude auth status --json           # correct flag
# NOT: --output-format json         # wrong, will error

---

Multi-turn sessions — the critical distinction

Claude Code uses a per-session-id file lock. The lock persists for several seconds (sometimes indefinitely) after the subprocess exits. This is the single most common source of failures.

Rule: first turn vs follow-up turns

Turn	Flag	Why
First	--session-id <uuid>	Creates the session file
Follow-up	--resume <uuid>	Continues without triggering the lock

--session-id on a follow-up always fails with "Session ID already in use" — even seconds after the first process exited.

const sessionFlag = isFirstTurn
  ? ['--session-id', claudeSessionId]
  : ['--resume', claudeSessionId];

spawn('claude', ['-p', prompt, '--output-format', 'stream-json',
  '--verbose', '--permission-mode', 'acceptEdits',
  '--model', model, ...sessionFlag], { ... });

Track "has had a first turn" per session:

private sessionsWithHistory = new Set<string>();
// After successful first turn:
sessionsWithHistory.add(sessionId);
// On subsequent turns: isFirstTurn = !sessionsWithHistory.has(sessionId)