CLI Control Surface: Print Mode, JSON, and Sessions

What You’ll Learn

Claude Code is not limited to its interactive terminal UI. Its released CLI surface can run one bounded task, emit machine-readable output, enforce a JSON Schema, limit agent turns, select a permission mode, and resume a saved session.

This lesson uses the Claude Code 2.1.226 command contract. Check claude --version and the current reference before relying on it in consequential automation.

Start with Print Mode

-p is short for --print: Claude runs non-interactively, writes the response, and exits.

claude -p "Summarize the changed files and report which tests ran."

Do not copy the meaning of -p from another CLI. Codex uses -p for a configuration profile, while Grok Build uses it for a single-turn prompt.

Choose an Output Contract

Use text for humans, JSON for one structured result, and stream JSON when a consumer needs incremental events.

claude -p --output-format text "Explain the failing test."
claude -p --output-format json "Return the repository status."
claude -p --output-format stream-json --include-partial-messages \
  "Report progress while reviewing this repository."

Treat output as untrusted data. Parse it, validate its shape, and keep it separate from shell command construction.

Require a JSON Schema

--json-schema constrains print-mode output. Quote the schema so the shell does not split or expand it.

claude -p \
  --json-schema '{"type":"object","properties":{"summary":{"type":"string"},"tests":{"type":"array","items":{"type":"string"}}},"required":["summary","tests"],"additionalProperties":false}' \
  "Review the current diff and return the requested fields."

A schema validates shape, not truth. The caller must still verify files, tests, and external state.

Bound Authority and Work

Turn limits and permission modes are separate controls:

claude -p \
  --max-turns 6 \
  --permission-mode plan \
  "Map the implementation path and risks without editing."

--max-turns limits the agent loop. --permission-mode determines how tool authority is handled. Neither replaces an OS sandbox, repository isolation, or review of destructive commands.

Continue Deliberately

Resume by an explicit session identifier when reproducibility matters:

claude -p --resume SESSION_ID \
  "Continue from the saved context and re-check the current worktree first."

--continue selects the most recent conversation in the current directory and is convenient but less explicit:

claude -p --continue "Continue only if the repository state still matches."

Saved context can be stale. Re-check instructions, permissions, branch, diff, and test state after every resume.

Production Checklist

• Pin and record the Claude Code version.
• Use -p only for Claude print mode.
• Select an output format and validate machine-readable output.
• Add a JSON Schema when downstream code depends on fields.
• Cap turns and set an intentional permission mode.
• Resume explicit sessions and revalidate the worktree.
• Never interpolate model output directly into a shell.

Next

Session 14 connects this bounded CLI workflow to MCP servers while keeping server trust and tool authority explicit.