Mode headless - Claude Code Docs

Ringkasan

Mode headless memungkinkan Anda menjalankan Claude Code secara terprogram dari skrip baris perintah dan alat otomasi tanpa UI interaktif apa pun.

Penggunaan dasar

Antarmuka baris perintah utama ke Claude Code adalah perintah claude. Gunakan flag --print (atau -p) untuk menjalankan dalam mode non-interaktif dan mencetak hasil akhir:

claude -p "Stage my changes and write a set of commits for them" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

Opsi Konfigurasi

Mode headless memanfaatkan semua opsi CLI yang tersedia di Claude Code. Berikut adalah yang utama untuk otomasi dan skripting:

Flag	Deskripsi	Contoh
`--print`, `-p`	Jalankan dalam mode non-interaktif	`claude -p "query"`
`--output-format`	Tentukan format output (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Lanjutkan percakapan berdasarkan ID sesi	`claude --resume abc123`
`--continue`, `-c`	Lanjutkan percakapan terbaru	`claude --continue`
`--verbose`	Aktifkan logging verbose	`claude --verbose`
`--append-system-prompt`	Tambahkan ke system prompt (hanya dengan `--print`)	`claude --append-system-prompt "Custom instruction"`
`--allowedTools`	Daftar alat yang diizinkan yang dipisahkan spasi, atau string daftar yang dipisahkan koma dari alat yang diizinkan	`claude --allowedTools mcp__slack mcp__filesystem` `claude --allowedTools "Bash(npm install),mcp__filesystem"`
`--disallowedTools`	Daftar alat yang ditolak yang dipisahkan spasi, atau string daftar yang dipisahkan koma dari alat yang ditolak	`claude --disallowedTools mcp__splunk mcp__github` `claude --disallowedTools "Bash(git commit),mcp__github"`
`--mcp-config`	Muat server MCP dari file JSON	`claude --mcp-config servers.json`
`--permission-prompt-tool`	Alat MCP untuk menangani prompt izin (hanya dengan `--print`)	`claude --permission-prompt-tool mcp__auth__prompt`

Untuk daftar lengkap opsi CLI dan fitur, lihat dokumentasi referensi CLI.

Percakapan multi-turn

Untuk percakapan multi-turn, Anda dapat melanjutkan percakapan atau melanjutkan dari sesi terbaru:

# Lanjutkan percakapan terbaru
claude --continue "Now refactor this for better performance"

# Lanjutkan percakapan tertentu berdasarkan ID sesi
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# Lanjutkan dalam mode non-interaktif
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive

Format Output

Output Teks (Default)

claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

Output JSON

Mengembalikan data terstruktur termasuk metadata:

claude -p "How does the data layer work?" --output-format json

Format respons:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

Output JSON Streaming

Mengalirkan setiap pesan saat diterima:

claude -p "Build an application" --output-format stream-json

Setiap percakapan dimulai dengan pesan sistem init awal, diikuti oleh daftar pesan pengguna dan asisten, diikuti oleh pesan sistem result akhir dengan statistik. Setiap pesan dipancarkan sebagai objek JSON terpisah.

Format Input

Input Teks (Default)

# Argumen langsung
claude -p "Explain this code"

# Dari stdin
echo "Explain this code" | claude -p

Input JSON Streaming

Aliran pesan yang disediakan melalui stdin di mana setiap pesan mewakili giliran pengguna. Ini memungkinkan beberapa giliran percakapan tanpa meluncurkan ulang biner claude dan memungkinkan memberikan panduan kepada model saat memproses permintaan. Setiap pesan adalah objek ‘Pesan Pengguna’ JSON, mengikuti format yang sama dengan skema pesan output. Pesan diformat menggunakan format jsonl di mana setiap baris input adalah objek JSON lengkap. Input JSON streaming memerlukan -p dan --output-format stream-json.

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Contoh Integrasi Agen

Bot Respons Insiden SRE

#!/bin/bash

# Agen respons insiden otomatis
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incident: $incident_description (Severity: $severity)" \
      --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Penggunaan
investigate_incident "Payment API returning 500 errors" "high"

Tinjauan Keamanan Otomatis

# Agen audit keamanan untuk pull request
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Penggunaan dan simpan ke file
audit_pr 123 > security-report.json

Asisten Hukum Multi-turn

# Tinjauan dokumen hukum dengan persistensi sesi
session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')

# Tinjau kontrak dalam beberapa langkah
claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
claude -p --resume "$session_id" "Check compliance with GDPR requirements"
claude -p --resume "$session_id" "Generate executive summary of risks"

Praktik Terbaik

Gunakan format output JSON untuk parsing respons secara terprogram:

# Parsing respons JSON dengan jq
result=$(claude -p "Generate code" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

Tangani kesalahan dengan baik - periksa kode keluar dan stderr:

if ! claude -p "$prompt" 2>error.log; then
    echo "Error occurred:" >&2
    cat error.log >&2
    exit 1
fi

Gunakan manajemen sesi untuk mempertahankan konteks dalam percakapan multi-turn

Pertimbangkan timeout untuk operasi yang berjalan lama:

timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"

Hormati batas laju saat membuat beberapa permintaan dengan menambahkan penundaan antar panggilan

Sumber Daya Terkait

Penggunaan dan kontrol CLI - Dokumentasi CLI lengkap
Alur kerja umum - Panduan langkah demi langkah untuk kasus penggunaan umum

Bangun dengan Claude Code

​Ringkasan

​Penggunaan dasar

​Opsi Konfigurasi

​Percakapan multi-turn

​Format Output

​Output Teks (Default)

​Output JSON

​Output JSON Streaming

​Format Input

​Input Teks (Default)

​Input JSON Streaming

​Contoh Integrasi Agen

​Bot Respons Insiden SRE

​Tinjauan Keamanan Otomatis

​Asisten Hukum Multi-turn

​Praktik Terbaik

​Sumber Daya Terkait