-p dengan prompt Anda dan opsi CLI apa pun:
claude -p). Untuk paket SDK Python dan TypeScript dengan output terstruktur, callback persetujuan alat, dan objek pesan asli, lihat dokumentasi Agent SDK lengkap.
Penggunaan dasar
Tambahkan bendera-p (atau --print) ke perintah claude apa pun untuk menjalankannya secara non-interaktif. Semua opsi CLI bekerja dengan -p, termasuk:
--continueuntuk melanjutkan percakapan--allowedToolsuntuk persetujuan otomatis alat--output-formatuntuk output terstruktur
Mulai lebih cepat dengan bare mode
Tambahkan--bare untuk mengurangi waktu startup dengan melewati penemuan otomatis hooks, skills, plugins, server MCP, auto memory, dan CLAUDE.md. Tanpanya, claude -p memuat konteks yang sama dengan sesi interaktif, termasuk apa pun yang dikonfigurasi di direktori kerja atau ~/.claude.
Bare mode berguna untuk CI dan skrip di mana Anda memerlukan hasil yang sama di setiap mesin. Hook di ~/.claude rekan kerja atau server MCP di .mcp.json proyek tidak akan berjalan, karena bare mode tidak pernah membacanya. Hanya bendera yang Anda berikan secara eksplisit yang berlaku.
Contoh ini menjalankan tugas ringkasan sekali pakai dalam bare mode dan pra-menyetujui alat Read sehingga panggilan selesai tanpa prompt izin:
Bare mode melewati pembacaan OAuth dan keychain. Autentikasi Anthropic harus berasal dari
ANTHROPIC_API_KEY atau apiKeyHelper dalam JSON yang diteruskan ke --settings. Amazon Bedrock, Google Cloud’s Agent Platform, dan Microsoft Foundry menggunakan kredensial penyedia biasa mereka.
--bare adalah mode yang direkomendasikan untuk panggilan skrip dan SDK, dan akan menjadi default untuk -p di rilis mendatang.Tugas latar belakang saat keluar
Jika Claude memulai tugas Bash latar belakang selama jalankanclaude -p, misalnya server dev atau build watch, tugas tersebut dihentikan sekitar lima detik setelah Claude mengembalikan hasil akhirnya dan stdin telah ditutup. Periode grace memungkinkan tugas yang selesai tepat setelah hasil masih memberikan outputnya. Sebelum v2.1.163, proses latar belakang yang tidak pernah keluar akan membuat invokasi claude -p tetap terbuka tanpa batas.
Subagen latar belakang dan alur kerja dikecualikan dari grace lima detik karena hasil mereka adalah bagian dari output akhir, jadi claude -p menunggu mereka selesai. Dari v2.1.182, tunggu itu dibatasi pada sepuluh menit secara default sehingga agen latar belakang yang macet tidak dapat membuat proses tetap terbuka tanpa batas. Sesuaikan batas dengan CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, atau atur ke 0 untuk menunggu tanpa batas.
Contoh
Contoh-contoh ini menyoroti pola CLI umum. Untuk CI dan panggilan skrip lainnya, tambahkan--bare sehingga mereka tidak mengambil apa pun yang kebetulan dikonfigurasi secara lokal.
Saluran data melalui Claude
Mode non-interaktif membaca stdin, sehingga Anda dapat menyalurkan data dan mengarahkan respons keluar seperti alat baris perintah lainnya. Contoh ini menyalurkan log build ke Claude dan menulis penjelasan ke file:--output-format json, payload respons mencakup total_cost_usd dan rincian biaya per-model, sehingga pemanggil skrip dapat melacak pengeluaran per invokasi tanpa berkonsultasi dengan dashboard penggunaan.
Sejak Claude Code v2.1.128, stdin yang disalurkan dibatasi pada 10MB. Jika Anda melampaui batas, Claude Code keluar dengan kesalahan yang jelas dan status bukan nol. Untuk bekerja dengan input yang lebih besar, tulis konten ke file dan referensikan jalur file dalam prompt Anda alih-alih menyalurkannya.
Tambahkan Claude ke skrip build
Anda dapat membungkus panggilan non-interaktif dalam skrip untuk menggunakan Claude sebagai linter atau reviewer khusus proyek. Skrippackage.json ini menyalurkan diff terhadap main ke Claude dan memintanya untuk melaporkan typo. Menyalurkan diff berarti Claude tidak memerlukan izin Bash untuk membacanya, dan tanda kutip ganda yang di-escape menjaga skrip portabel ke Windows:
Dapatkan output terstruktur
Gunakan--output-format untuk mengontrol bagaimana respons dikembalikan:
text(default): output teks biasajson: JSON terstruktur dengan hasil, ID sesi, dan metadatastream-json: JSON yang dibatasi baris baru untuk streaming real-time
result:
--output-format json dengan --json-schema dan definisi JSON Schema. Respons mencakup metadata tentang permintaan (ID sesi, penggunaan, dll.) dengan output terstruktur di bidang structured_output.
Contoh ini mengekstrak nama fungsi dan mengembalikannya sebagai array string:
claude keluar dengan Error: --json-schema is not a valid JSON Schema diikuti oleh diagnostik validator. Claude Code menerima skema yang menggunakan kata kunci format, seperti "format": "email", tetapi memperlakukan format sebagai anotasi dan tidak memberlakukannya. Sebelum v2.1.205, Claude Code secara diam-diam mengabaikan skema yang tidak valid dan mengembalikan teks yang tidak terstruktur, dan memperlakukan skema apa pun yang berisi format sebagai tidak valid.
Streaming respons
Gunakan--output-format stream-json dengan --verbose dan --include-partial-messages untuk menerima token saat dihasilkan. Setiap baris adalah objek JSON yang mewakili acara:
result dengan teks respons akhir, biaya, dan metadata sesi. Sebelum v2.1.208, menyalurkan respons besar dapat memotong baris terakhir dan menghilangkan pesan result.
Contoh berikut menggunakan jq untuk memfilter delta teks dan menampilkan hanya teks streaming. Bendera -r menampilkan string mentah (tanpa tanda kutip) dan -j bergabung tanpa baris baru sehingga token streaming terus menerus:
system/api_retry sebelum mencoba ulang. Anda dapat menggunakan ini untuk menampilkan kemajuan percobaan ulang atau menerapkan logika backoff kustom.
Acara
system/init melaporkan metadata sesi termasuk model, alat, server MCP, dan plugin yang dimuat. Ini adalah acara pertama dalam aliran kecuali acara startup mendahuluinya:
- Acara
plugin_install, ketikaCLAUDE_CODE_SYNC_PLUGIN_INSTALLdiatur. - Acara
hook_started,hook_progress, danhook_response, saat hookSessionStartatauSetupyang dikonfigurasi berjalan. Ini streaming saat hook menghasilkannya. Claude Code v2.1.169 hingga v2.1.203 mengirimkannya dalam satu batch setelah hook selesai, masih sebelumsystem/init; v2.1.204 mengembalikan pengiriman langsung.
capabilities opsional dari string yang menamai perilaku protokol yang diimplementasikan versi Claude Code ini, seperti interrupt_receipt_v1. Periksanya untuk mendeteksi fitur alih-alih membandingkan string versi, dan abaikan nilai yang tidak Anda kenali. Bidang ini memerlukan Claude Code v2.1.205 atau lebih baru dan tidak ada di versi sebelumnya. Lihat SDKSystemMessage untuk daftar kemampuan.
Gunakan bidang plugin untuk gagal CI ketika plugin tidak dimuat:
Ketika
CLAUDE_CODE_SYNC_PLUGIN_INSTALL diatur, Claude Code memancarkan acara system/plugin_install saat plugin marketplace dipasang sebelum giliran pertama. Gunakan ini untuk menampilkan kemajuan pemasangan di UI Anda sendiri.
Untuk streaming programatis dengan callback dan objek pesan, lihat Stream responses in real-time dalam dokumentasi Agent SDK.
Persetujuan otomatis alat
Gunakan--allowedTools untuk membiarkan Claude menggunakan alat tertentu tanpa meminta. Contoh ini menjalankan suite pengujian dan memperbaiki kegagalan, memungkinkan Claude untuk menjalankan perintah Bash dan membaca/mengedit file tanpa meminta izin:
dontAsk menolak apa pun yang tidak ada dalam aturan permissions.allow Anda atau set perintah read-only, yang berguna untuk CI runs yang terkunci. AskUserQuestion, alat konektor organisasi Anda atur ke ask, dan alat MCP yang ditandai requiresUserInteraction ditolak bahkan ketika aturan allow cocok.
acceptEdits memungkinkan Claude menulis file tanpa meminta dan juga persetujuan otomatis perintah filesystem umum seperti mkdir, touch, mv, dan cp. Perintah shell lainnya dan permintaan jaringan masih memerlukan entri --allowedTools atau aturan permissions.allow, jika tidak run akan berhenti ketika salah satu dicoba:
Buat komit
Contoh ini meninjau perubahan yang dipentaskan dan membuat komit dengan pesan yang sesuai:--allowedTools menggunakan sintaks aturan izin. Spasi di akhir * memungkinkan pencocokan awalan, jadi Bash(git diff *) memungkinkan perintah apa pun yang dimulai dengan git diff. Spasi sebelum * penting: tanpanya, Bash(git diff*) juga akan cocok dengan git diff-index.
skills yang dipanggil pengguna dan perintah kustom bekerja dalam mode
-p: sertakan /skill-name dalam string prompt dan Claude Code memperluasnya sebelum menjalankan. Perintah bawaan yang hanya berjalan di antarmuka terminal, seperti /login, tidak tersedia dalam mode -p. /model, /effort, /fast, /color, dan /rename menerima nilai sebagai argumen, misalnya /model sonnet, dan /mcp tanpa argumen mencetak ringkasan teks status server; bentuk-bentuk ini memerlukan Claude Code v2.1.205 atau lebih baru dan mengikuti catatan ketersediaan setiap perintah. Untuk mengubah pengaturan dari invokasi -p, berikan key=value ke /config, misalnya /config thinking=false.Sesuaikan prompt sistem
Gunakan--append-system-prompt untuk menambahkan instruksi sambil mempertahankan perilaku default Claude Code. Contoh ini menyalurkan diff PR ke Claude dan menginstruksikannya untuk meninjau kerentanan keamanan:
--system-prompt untuk sepenuhnya mengganti prompt default.
Lanjutkan percakapan
Gunakan--continue untuk melanjutkan percakapan terbaru, atau --resume dengan ID sesi untuk melanjutkan percakapan tertentu. Contoh ini menjalankan tinjauan, kemudian mengirim prompt tindak lanjut:
Langkah berikutnya
- Agent SDK quickstart: bangun agen pertama Anda dengan Python atau TypeScript
- CLI reference: semua bendera dan opsi CLI
- GitHub Actions: gunakan Agent SDK dalam alur kerja GitHub
- GitLab CI/CD: gunakan Agent SDK dalam pipeline GitLab