Referensi CLI

Semua perintah di Perch CLI: subperintah perch yang Anda jalankan dari shell, dan perintah garis miring yang Anda pakai di dalam sesi interaktif.

Perch CLI adalah operator lengkap di terminal Anda. CLI menjalankan mesin dan pemeriksa sitasi yang sama dengan aplikasi desktop, dan bekerja dari folder tempat Anda berada. Halaman ini adalah referensi perintah lengkap: subperintah perch yang Anda jalankan dari shell, flag global yang membentuk sebuah sesi, dan perintah garis miring yang Anda ketik setelah Perch berjalan.

Instal dan masuk

npm install -g perchai-cli   # Node 18+
perch login                  # opens a browser tab, saves your session
perch                         # start working in the current folder

Dua cara menjalankan

Ada dua mode, dan perbedaannya adalah apakah Anda tetap berada dalam sesi atau menjalankan satu tugas lalu keluar.

Interaktif. Jalankan perch tanpa argumen untuk membuka chat di direktori saat ini. CLI membaca file di sana, menerima tugas dalam bahasa sehari-hari, dan menyimpan thread. Perintah garis miring (di bawah) mengarahkannya selagi bekerja.
Sekali jalan. Jalankan perch run "<task>" untuk mengeksekusi satu tugas lalu kembali. Tambahkan --json untuk output yang dapat dibaca mesin. Bentuk inilah yang Anda pakai dalam skrip atau pipe.

perch                                   # interactive session in .
perch run "Check March invoices for duplicates."   # one task, then exit
perch run "Draft the venue section" --persona quill --json

Perintah shell

Perintah yang Anda jalankan dari shell sebagai perch <command>.

Perintah	Fungsinya
`perch`	Membuka chat Perch interaktif di direktori saat ini.
`perch login`	Membuka proses masuk di browser dan menyimpan sesi terminal ini.
`perch status`	Menampilkan status autentikasi tersimpan dan koneksi aplikasi.
`perch logout`	Menghapus sesi autentikasi CLI yang tersimpan.
`perch skills [name]`	Menampilkan daftar skill inti Perch, atau mencetak isi satu skill.
`perch run "<task>"`	Menjalankan satu tugas berbahasa alami melalui operator.
`perch ap evidence <folder>`	Menyiapkan bukti, kasus, metrik, dan artefak grafik untuk audit AP.
`perch ap packet <folder>`	Menghasilkan paket audit AP lengkap beserta laporannya.
`perch test ap <folder>`	Menjalankan evidence + packet dan mengeluarkan tanda terima lulus/gagal.
`perch byok use <provider> \| off`	Menjalankan giliran terminal ini dengan kunci cloud yang tersimpan di akun Anda, atau kembali ke Perch.
`perch byok list \| status \| test \| set \| remove`	Mengelola kunci di akun Anda tanpa meninggalkan terminal.
`perch byolm set <url> <model>`	Mengarahkan Perch ke model lokal Anda sendiri (Ollama, LM Studio, llama.cpp).
`perch byolm status \| clear \| test`	Menampilkan, menghapus, atau menguji model lokal.

Flag global

Flag ini membentuk sebuah sesi dan dapat diberikan ke perch atau perch run:

Flag	Nilai	Kegunaan
`--cwd <dir>`	path apa pun	Bekerja dari folder selain folder saat ini.
`--permission <mode>`	`default`, `auto_review`, `take_the_wheel`, `plan`	Menentukan seberapa banyak yang dapat dilakukan Perch tanpa bertanya. Lihat Mode izin.
`--mode <mode>`	`ask`, `agents`, `plan`	Menentukan mode chat untuk sesi.
`--persona <persona>`	`saffron`, `quill`	Memulai dengan satu gaya bahasa. Lihat Persona.
`--model <tier>`	`standard`, `standard max`, `pro`, `pro max`	Menyematkan satu tingkatan Roost untuk eksekusi ini.
`--thinking <on\|off>`	`on`, `off`	Mengaktifkan atau menonaktifkan extended thinking untuk model yang dipilih.
`--thread <id>`	id thread	Melanjutkan thread tertentu (dengan `perch run`).
`--json`	-	Mengeluarkan output yang dapat dibaca mesin (dengan `perch run`).

Perintah garis miring

Setelah berada di sesi interaktif, ketik perintah garis miring di prompt. Selagi Perch bekerja, Anda juga bisa mengetik teks pengarah lalu menekan Enter; Ctrl-C menghentikan giliran saat ini dan Ctrl-E membuka detail.

Bagian ini berisi daftarnya. Untuk kapan sebaiknya memakai masing-masing perintah dan apa yang Anda dapatkan, lihat Perintah garis miring.

Menjalankan pekerjaan

Perintah	Fungsinya
`/goal <objective>`	Bekerja secara otonom menuju sebuah tujuan lintas giliran sampai audit penyelesaian lolos.
`/goal [status\|pause\|resume\|clear]`	Memeriksa atau mengendalikan goal yang aktif. Goal tetap ada meski Anda keluar, jadi `/goal resume` berfungsi di sesi berikutnya.
`/verify [text]`	Memeriksa ulang jawaban terakhir, atau teks yang ditempel, terhadap sumber Anda yang sudah diindeks.
`/verify --changed`	Hanya memeriksa ulang klaim yang sumbernya berubah sejak `/verify` terakhir Anda.

Sesi dan bantuan

Perintah	Fungsinya
`/help`	Menampilkan daftar perintah lengkap.
`/status`	Menampilkan cwd, autentikasi, mode, persona, izin, dan thread.
`/context`	Menampilkan meteran konteks dan detail pemadatan (compaction).
`/clear`	Menghapus memori percakapan lokal dari sesi terminal ini.
`/exit`	Keluar dari Perch CLI.

Akun

Perintah	Fungsinya
`/login`	Masuk melalui OAuth di browser.
`/logout`	Menghapus autentikasi CLI yang tersimpan.

Mengarahkan pekerjaan

Perintah	Fungsinya
`/persona [saffron\|quill]`	Menampilkan atau mengganti gaya bahasa. Persona.
`/mode [ask\|agents\|plan]`	Menampilkan atau menentukan mode chat.
`/permission [mode]`	Menampilkan atau menentukan tingkat otonomi untuk giliran berikutnya. Mode izin.
`/model [tier\|name]`	Menampilkan atau menentukan model Anda: tingkatan Roost atau model tertentu yang disematkan. Tingkatan model.
`/thinking [on\|off]`	Menampilkan status atau mengaktifkan/menonaktifkan extended thinking untuk model yang dipilih.
`/byok [provider\|off]`	Menampilkan atau mengganti kunci cloud tersimpan yang dipakai giliran terminal ini. Pakai kunci API sendiri.
`/local-tools [on\|off]`	Menampilkan status atau mengaktifkan/menonaktifkan tool shell dan file lokal.
`/cwd [dir]`	Menampilkan atau mengganti direktori kerja.
`/thread [new\|id]`	Menampilkan, mereset, atau menentukan id thread saat ini.

/permissions adalah alias

/permissions melakukan hal yang sama dengan /permission; kedua ejaan sama-sama berfungsi.

Memori, penggunaan, dan skill

Perintah	Fungsinya
`/memory-audit <text>`	Memeriksa apakah sebuah catatan akan disimpan ke memori, dan alasannya. Memori.
`/usage`	Menampilkan penggunaan Perch Token yang sudah termasuk dalam paket Anda dan penggunaan sesi ini.
`/skills [name]`	Menampilkan daftar skill inti Perch, atau menampilkan isi satu skill.

Mendelegasikan pekerjaan

Perintah	Fungsinya
`/delegate <task>`	Menyerahkan tugas yang cakupannya jelas ke agen latar belakang untuk dieksekusi secara asinkron, lalu ditinjau.
`/bg <task>`	Singkatan untuk `/delegate`.

Gunakan /delegate jika tugasnya berdiri sendiri dan Anda lebih suka terus bekerja daripada menontonnya berjalan. Agen mengeksekusi tugas di latar belakang dan mengembalikan hasilnya untuk ditinjau, sehingga pekerjaan panjang tidak pernah memblokir sesi.

Mode izin

Mode izin mengatur seberapa banyak yang dikerjakan Perch sebelum berhenti untuk bertanya. Tentukan dengan /permission di dalam sesi atau --permission saat memulai.

Perch memutuskan dalam dua langkah. Seperangkat aturan tetap berjalan lebih dulu, secara instan: membaca file, mengedit di dalam ruang kerja Anda, dan menjalankan perintah build dan test milik proyek langsung jalan; force push, penulisan ulang riwayat, dan penghapusan massal selalu berhenti untuk menunggu Anda; dan daftar blokir path sensitif (kunci, kredensial, folder sistem) ditolak di semua mode. Sisanya adalah sekumpulan kecil tindakan berdampak yang tidak bisa diputuskan oleh aturan tersebut, dan cara menangani sisa inilah yang membedakan setiap mode.

Mode	Yang berjalan tanpa bertanya
Default	Hanya membaca. Setiap penulisan, perintah, pengiriman, dan penghapusan meminta persetujuan Anda dulu.
Auto Review	Pekerjaan berisiko rendah dan menengah yang dapat dibatalkan berjalan sendiri. Setiap tindakan berdampak di luar itu diperiksa oleh peninjau terpisah, yang hanya bertanya kepada Anda jika ragu.
Take the Wheel	Semuanya, tanpa bertanya.
Plan	Hanya baca. Tool yang mengubah sesuatu tetap diblokir sampai Anda menyetujui sebuah rencana.

Mulai dengan ketat

Default adalah mode yang tepat untuk pekerjaan sungguhan: tidak ada tindakan yang tidak dapat dibatalkan yang terjadi tanpa Anda lihat. Pindah ke Auto Review setelah Anda memercayai alurnya untuk folder tertentu, dan simpan Take the Wheel untuk tugas yang sudah pernah Anda lihat dijalankan Perch dengan benar.

Cara Auto Review memutuskan

Auto Review adalah mode lepas tangan yang tetap menempatkan penjaga di depan pekerjaan yang berdampak. Alih-alih berhenti di setiap penulisan atau perintah, mode ini mengirim setiap tindakan yang tidak bisa diloloskan oleh aturan tetap ke peninjau terpisah, yang mengambil keputusan sebelum tindakan itu dijalankan:

Tindakan Allowed (diizinkan) dijalankan, dan giliran berlanjut tanpa mengganggu Anda.
Tindakan Blocked (diblokir) tidak dijalankan. Perch diminta mencari cara yang lebih aman untuk mencapai tujuan, bukan mengakali blokir itu, lalu terus bekerja.
Perch bertanya kepada Anda saat peninjau tidak bisa memutuskan, saat jenis tindakan yang sama diblokir beberapa kali berturut-turut, atau untuk tindakan berisiko tertinggi yang tidak pernah ditinjau secara otomatis sama sekali: force push dan penghapusan massal selalu berhenti untuk menunggu konfirmasi Anda.

Peninjau melihat permintaan Anda dan tindakan yang akan diambil Perch, tidak lebih. Peninjau tidak membaca isi file atau output perintah, sehingga instruksi yang tersembunyi di dalam halaman web atau dokumen tidak dapat membujuknya untuk menyetujui sesuatu. Jika peninjau sedang tidak tersedia, Perch bertanya kepada Anda alih-alih menebak. Pemeriksaan ini memakai sebagian kecil penggunaan yang sudah termasuk dalam paket Anda, sebagai imbalan atas mode yang berjalan tanpa diawasi tanpa berjalan secara buta.

Garis yang ditarik Auto Review adalah antara yang dapat dibatalkan dan yang tidak dapat dibatalkan, bukan antara yang mudah dan yang sulit. Mengedit file yang dapat Anda kembalikan berbeda kategori dengan mengirim email, dan peninjau memperlakukannya demikian.

Tingkatan model

/model dan --model menerima tingkatan Roost, yang membiarkan Roost memilih model yang mumpuni untuk setiap tugas dengan tarif standar:

auto: biarkan Roost memilih.
standard, standard max: pekerjaan sehari-hari.
pro, pro max: tugas yang paling sulit.

Anda juga bisa menyematkan model tertentu (misalnya /model claude-opus-5.5 di Pro, atau build GLM, Kimi, MiniMax, DeepSeek, atau Qwen tertentu) saat Anda memerlukan model yang pasti dari awal sampai akhir. Jalankan /model tanpa argumen untuk melihat pilihan saat ini dan daftar lengkapnya.

Pakai model sendiri

Ada dua perintah, tergantung di komputer siapa model itu berjalan.

perch byok menjalankan giliran dengan kunci cloud yang tersimpan di akun Anda. Kuncinya sendiri disimpan di akun dalam keadaan terenkripsi, jadi kunci yang ditambahkan di web sudah tersedia di sini; memilihnya berlaku per perangkat.

perch byok list                  # keys saved on your account
perch byok use openai            # run this terminal's turns on that key
perch byok status                # what turns are running on right now
perch byok off                   # go back to Roost

Anda juga bisa menambahkan dan menguji kunci dari sini, termasuk endpoint Anda sendiri yang kompatibel dengan OpenAI:

perch byok set openai --key sk-...
perch byok set custom --key sk-... --url https://api.example.com/v1 --model acme/model-x
perch byok test                  # one real request against the selected key
perch byok remove openai

perch byolm mengarahkan Perch ke model yang Anda jalankan sendiri, seperti Ollama, LM Studio, atau llama.cpp, alih-alih Roost. Endpoint-nya tidak pernah meninggalkan komputer Anda, itulah sebabnya perintah ini hanya untuk CLI.

perch byolm set http://localhost:11434/v1 llama3.1   # register a local model
perch byolm test                                      # probe that it responds
perch byolm status                                    # show the current local model
perch byolm clear                                     # go back to Roost

Giliran dengan salah satu dari keduanya tidak dihitung terhadap Perch Token Anda, dan Perch tidak akan diam-diam beralih ke model yang di-host jika endpoint Anda gagal. Lihat Pakai kunci API sendiri.

Menghubungkan tool

CLI terhubung ke server MCP untuk kemampuan di luar folder. Anda menambahkannya di .perch/mcp.json, lalu tool yang terhubung muncul bersama tool bawaan. Lihat Server MCP.

Browser agen hanya ada di desktop, jadi pekerjaan browser tidak tersedia di CLI. Jika Anda memerlukannya dari alur kerja yang dijalankan dari terminal, jalankan bagian itu di aplikasi desktop.

Langkah berikutnya

Persona

Dua gaya bahasa, satu mesin. Tool sama dan tugas sama, gaya bahasa berbeda.

Pemecahan masalah

Beberapa hal yang bisa salah, beserta perbaikannya.

Di halaman ini