​
Gambaran Umum

Mode headless memungkinkan Anda menjalankan Claude Code secara programatis dari skrip command line dan alat otomasi tanpa UI interaktif apa pun.

​
Penggunaan Dasar

Antarmuka command-line utama untuk 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 \
  --cwd /path/to/project

​
Opsi Konfigurasi

SDK memanfaatkan semua opsi CLI yang tersedia di Claude Code. Berikut adalah yang utama untuk penggunaan SDK:

FlagDeskripsiContoh
--print, -pJalankan dalam mode non-interaktifclaude -p "query"
--output-formatTentukan format output (text, json, stream-json)claude -p --output-format json
--resume, -rLanjutkan percakapan berdasarkan ID sesiclaude --resume abc123
--continue, -cLanjutkan percakapan terbaruclaude --continue
--verboseAktifkan logging verboseclaude --verbose
--append-system-promptTambahkan ke system prompt (hanya dengan --print)claude --append-system-prompt "Custom instruction"
--allowedToolsDaftar alat yang diizinkan dipisahkan spasi, atau

string daftar alat yang diizinkan dipisahkan koma		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsDaftar alat yang ditolak dipisahkan spasi, atau

string daftar alat yang ditolak dipisahkan koma		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configMuat server MCP dari file JSONclaude --mcp-config servers.json
--permission-prompt-toolAlat 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 spesifik 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 binary claude dan memungkinkan memberikan panduan kepada model saat sedang memproses permintaan.

Setiap pesan adalah objek JSON ‘User message’, 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 Agent

​
Bot Respons Insiden SRE

#!/bin/bash

# Agent 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"

​
Review Keamanan Otomatis

# Agent 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

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

# Review 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 programatis respons:

    # Parse 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 error 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 rate saat membuat beberapa permintaan dengan menambahkan jeda antara panggilan

​
Sumber Daya Terkait