claude-print-automation

name	claude-print-automation
description	Use when preparing, running, or debugging non-interactive Claude Code with `claude --print`, output-format text/json/stream-json, input-format text/stream-json, JSON schema validation, budget caps, fallback model, no session persistence, prompt suggestions, or trusted-directory CI-style runs.

Claude Print Automation

Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.

Use this skill for non-interactive Claude Code runs: claude --print, -p, JSON output, stream-json input/output, partial messages, hook event streams, JSON schema validation, budget caps, fallback model, prompt suggestions, no-persistence runs, and CI-style reports.

Inspect First

Verify the installed CLI:

python3 "$PLUGIN_ROOT/scripts/claude_code_inspector.py" --commands "plugin validate" doctor auto-mode --json

If the user supplied a binary path, pass --claude "$CLAUDE_CLI_PATH".

Command Assembly

Build commands from these decisions, in order:

1. Trust boundary: confirm the directory is trusted because print mode skips the workspace trust dialog.
2. Permission/tool surface: choose --permission-mode, --tools, --allowedTools, and --disallowedTools.
3. Context: add --add-dir, explicit files, --mcp-config, --settings, --agents, or --plugin-dir only when needed.
4. Prompt input: use an argument for short prompts or stdin for long structured prompts.
5. Output contract: choose --output-format text|json|stream-json, --json-schema, and partial-message/hook-event streaming.
6. Cost/session: choose --max-budget-usd, --fallback-model, and --no-session-persistence.

Common patterns:

claude --print --output-format json --permission-mode plan "Inspect this repo and report risks only."
claude --print --output-format json --json-schema "$SCHEMA" - < prompt.md
claude --print --output-format stream-json --include-partial-messages --input-format stream-json
claude --print --tools "Read,Grep,Glob" --permission-mode plan "Summarize this codebase."

Use --bare when startup customizations, plugin sync, hooks, keychain reads, or CLAUDE.md auto-discovery could contaminate a reproducible run. Provide explicit context in that mode.

Use --safe-mode when customizations are suspected to be broken but normal auth/model/tool defaults should remain available.

Structured Output

Use --json-schema for machine-consumed final answers. Keep the schema small and validate it before use. For streaming automation, parse JSON lines incrementally; do not load a large stream into memory as one array.

Use --include-hook-events only when auditing hook behavior. Hook events can expose tool inputs or local paths, so summarize before sharing.

Safety Boundaries

• Do not use dangerous skip-permissions flags unless the user explicitly selected an external sandbox.
• Do not pass secrets in prompt arguments, JSON schema, settings JSON, MCP config, or tool allow/deny examples.
• Do not use --settings JSON that embeds tokens; reference env vars or ignored local files.
• Do not set --permission-mode dontAsk or bypassPermissions for untrusted repositories.
• Do not run cloud or update workflows from print automation unless the task asks for them.

Failure Triage

1. Re-run claude --help through the inspector if a flag is unknown.
2. Try --safe-mode if customization loading appears broken.
3. Try --bare with explicit context if keychain/plugin/hook/CLAUDE.md discovery is suspect.
4. Use --debug-file <path> only to a local ignored path and report indicators, not raw secrets.

Completion Standard

Report the exact command, trust boundary, permission mode, tool restrictions, input/output formats, budget/session persistence choices, and verification or blocker.