คู่มืออ้างอิง CLI

ทุกคำสั่งใน Perch CLI ทั้งคำสั่งย่อยของ perch ที่คุณรันจากเชลล์ และคำสั่งสแลชที่คุณใช้ภายในเซสชันแบบโต้ตอบ

Perch CLI คือ operator เต็มรูปแบบในเทอร์มินัลของคุณ รันเอนจินและตัวตรวจสอบการอ้างอิงตัวเดียวกับแอปเดสก์ท็อป โดยทำงานจากโฟลเดอร์ที่คุณอยู่ หน้านี้คือคู่มืออ้างอิงคำสั่งฉบับสมบูรณ์ ได้แก่ คำสั่งย่อย perch ที่คุณรันจากเชลล์ flag ส่วนกลางที่กำหนดลักษณะของเซสชัน และคำสั่งสแลชที่คุณพิมพ์เมื่อ Perch ทำงานอยู่

ติดตั้งและลงชื่อเข้าใช้

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

สองวิธีในการรัน

มีสองโหมด และความต่างอยู่ที่คุณจะอยู่ในเซสชันต่อ หรือสั่งงานเดียวแล้วออก

แบบโต้ตอบ รัน perch โดยไม่ใส่อาร์กิวเมนต์เพื่อเปิดแชตในไดเรกทอรีปัจจุบัน มันจะอ่านไฟล์ในนั้น รับงานเป็นภาษาธรรมดา และเก็บเธรดไว้ คำสั่งสแลช (ด้านล่าง) ใช้กำกับทิศทางมันระหว่างที่ทำงาน
แบบสั่งครั้งเดียว รัน perch run "<task>" เพื่อทำงานเดียวแล้วกลับมา เพิ่ม --json เพื่อให้ได้เอาต์พุตที่เครื่องอ่านได้ นี่คือรูปแบบที่คุณใช้ในสคริปต์หรือส่งต่อผ่าน 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

คำสั่งเชลล์

คำสั่งที่คุณรันจากเชลล์ในรูปแบบ perch <command>

คำสั่ง	สิ่งที่ทำ
`perch`	เปิดแชต Perch แบบโต้ตอบในไดเรกทอรีปัจจุบัน
`perch login`	เปิดการลงชื่อเข้าใช้ผ่านเบราว์เซอร์ และบันทึกเซสชันของเทอร์มินัลนี้
`perch status`	แสดงสถานะการยืนยันตัวตนที่บันทึกไว้และสถานะการเชื่อมต่อกับแอป
`perch logout`	ล้างเซสชันการยืนยันตัวตนของ CLI ที่บันทึกไว้
`perch skills [name]`	แสดงรายการสกิลหลักของ Perch หรือพิมพ์เนื้อหาของสกิลหนึ่งรายการ
`perch run "<task>"`	รันงานหนึ่งงานที่เขียนเป็นภาษาธรรมชาติผ่าน operator
`perch ap evidence <folder>`	เตรียมหลักฐาน เคส ตัวชี้วัด และอาร์ติแฟกต์กราฟสำหรับการตรวจสอบเจ้าหนี้การค้า (AP)
`perch ap packet <folder>`	สร้างชุดเอกสารการตรวจสอบ AP ฉบับเต็มและรายงาน
`perch test ap <folder>`	รัน evidence + packet แล้วออกบันทึกผลแบบผ่าน/ไม่ผ่าน
`perch byok use <provider> \| off`	รันเทิร์นของเทอร์มินัลนี้บนคีย์คลาวด์ที่บันทึกไว้ในบัญชีของคุณ หรือกลับไปใช้ Perch
`perch byok list \| status \| test \| set \| remove`	จัดการคีย์ในบัญชีของคุณโดยไม่ต้องออกจากเทอร์มินัล
`perch byolm set <url> <model>`	ชี้ Perch ไปที่โมเดลในเครื่องของคุณเอง (Ollama, LM Studio, llama.cpp)
`perch byolm status \| clear \| test`	แสดง ลบ หรือทดสอบการตอบสนองของโมเดลในเครื่อง

flag ส่วนกลาง

flag เหล่านี้กำหนดลักษณะของเซสชัน และส่งให้ perch หรือ perch run ได้

Flag	ค่า	จุดประสงค์
`--cwd <dir>`	พาธใดก็ได้	ทำงานจากโฟลเดอร์อื่นที่ไม่ใช่โฟลเดอร์ปัจจุบัน
`--permission <mode>`	`default`, `auto_review`, `take_the_wheel`, `plan`	กำหนดว่า Perch ทำอะไรได้มากแค่ไหนโดยไม่ต้องถาม ดูโหมดสิทธิ์
`--mode <mode>`	`ask`, `agents`, `plan`	กำหนดโหมดแชตของเซสชัน
`--persona <persona>`	`saffron`, `quill`	เริ่มด้วยน้ำเสียงที่เลือก ดูเพอร์โซนา
`--model <tier>`	`standard`, `standard max`, `pro`, `pro max`	ปักหมุดระดับของ Roost สำหรับการรันนั้น
`--thinking <on\|off>`	`on`, `off`	เปิดหรือปิด extended thinking ของโมเดลที่เลือก
`--thread <id>`	id ของเธรด	ทำงานต่อในเธรดที่ระบุ (ใช้กับ `perch run`)
`--json`	-	ส่งเอาต์พุตที่เครื่องอ่านได้ (ใช้กับ `perch run`)

คำสั่งสแลช

เมื่อคุณอยู่ในเซสชันแบบโต้ตอบ ให้พิมพ์คำสั่งสแลชที่ช่องพรอมต์ ระหว่างที่ Perch ทำงาน คุณยังพิมพ์ข้อความกำกับทิศทางแล้วกด Enter ได้ด้วย Ctrl-C หยุดเทิร์นปัจจุบัน และ Ctrl-E ขยายรายละเอียด

ส่วนนี้เป็นรายการคำสั่ง ส่วนว่าควรใช้แต่ละคำสั่งเมื่อไรและจะได้อะไรกลับมา ดูที่คำสั่งสแลช

รันงาน

คำสั่ง	สิ่งที่ทำ
`/goal <objective>`	ทำงานไปสู่เป้าหมายอย่างอิสระต่อเนื่องหลายเทิร์น จนกว่าจะผ่านการตรวจสอบความเสร็จสมบูรณ์
`/goal [status\|pause\|resume\|clear]`	ตรวจดูหรือควบคุมเป้าหมายที่กำลังทำงานอยู่ เป้าหมายยังคงอยู่แม้คุณจะออกจากโปรแกรม `/goal resume` จึงใช้ได้ในเซสชันภายหลัง
`/verify [text]`	ตรวจคำตอบล่าสุดหรือข้อความที่วางไว้ซ้ำกับแหล่งที่มาที่ทำดัชนีไว้ของคุณ
`/verify --changed`	ตรวจซ้ำเฉพาะข้อความกล่าวอ้างที่แหล่งที่มาเปลี่ยนไปตั้งแต่ `/verify` ครั้งล่าสุดของคุณ

เซสชันและความช่วยเหลือ

คำสั่ง	สิ่งที่ทำ
`/help`	แสดงรายการคำสั่งทั้งหมด
`/status`	แสดง cwd การยืนยันตัวตน โหมด เพอร์โซนา สิทธิ์ และเธรด
`/context`	แสดงมาตรวัดบริบทและรายละเอียดการบีบอัดบริบท
`/clear`	ล้างหน่วยความจำบทสนทนาในเครื่องของเซสชันเทอร์มินัลนี้
`/exit`	ออกจาก Perch CLI

บัญชี

คำสั่ง	สิ่งที่ทำ
`/login`	ลงชื่อเข้าใช้ผ่าน OAuth ในเบราว์เซอร์
`/logout`	ล้างการยืนยันตัวตนของ CLI ที่บันทึกไว้

กำกับทิศทางงาน

คำสั่ง	สิ่งที่ทำ
`/persona [saffron\|quill]`	แสดงหรือสลับน้ำเสียง เพอร์โซนา
`/mode [ask\|agents\|plan]`	แสดงหรือตั้งค่าโหมดแชต
`/permission [mode]`	แสดงหรือตั้งค่าระดับความเป็นอิสระสำหรับเทิร์นถัดไป โหมดสิทธิ์
`/model [tier\|name]`	แสดงหรือตั้งค่าโมเดลของคุณ เป็นระดับของ Roost หรือการปักหมุดโมเดลที่ระบุชัดเจน ระดับโมเดล
`/thinking [on\|off]`	แสดงหรือเปิดปิด extended thinking ของโมเดลที่เลือก
`/byok [provider\|off]`	แสดงหรือสลับคีย์คลาวด์ที่บันทึกไว้ซึ่งเทิร์นของเทอร์มินัลนี้ใช้รัน ใช้คีย์ API ของคุณเอง
`/local-tools [on\|off]`	แสดงหรือเปิดปิดเครื่องมือเชลล์และเครื่องมือไฟล์ในเครื่อง
`/cwd [dir]`	แสดงหรือเปลี่ยนไดเรกทอรีทำงาน
`/thread [new\|id]`	แสดง รีเซ็ต หรือตั้งค่า id ของเธรดปัจจุบัน

/permissions เป็นชื่อเรียกแทน

/permissions ทำงานเหมือนกับ /permission สะกดแบบไหนก็ใช้ได้

หน่วยความจำ การใช้งาน และสกิล

คำสั่ง	สิ่งที่ทำ
`/memory-audit <text>`	ตรวจว่าโน้ตหนึ่งจะถูกบันทึกลงหน่วยความจำหรือไม่ และเพราะอะไร หน่วยความจำ
`/usage`	แสดงการใช้งาน Perch Token ที่รวมอยู่ในแพ็กเกจของคุณ และการใช้งานของเซสชันนี้
`/skills [name]`	แสดงรายการสกิลหลักของ Perch หรือแสดงเนื้อหาของสกิลหนึ่งรายการ

มอบหมายงาน

คำสั่ง	สิ่งที่ทำ
`/delegate <task>`	ส่งงานที่มีขอบเขตชัดเจนให้เอเจนต์เบื้องหลังรันแบบ async พร้อมการรีวิว
`/bg <task>`	รูปย่อของ `/delegate`

ใช้ /delegate เมื่องานจบในตัวเอง และคุณอยากทำงานอื่นต่อมากกว่านั่งดูมันรัน เอเจนต์จะทำงานในเบื้องหลังและส่งผลลัพธ์กลับมาให้รีวิว งานที่ใช้เวลานานจึงไม่บล็อกเซสชัน

โหมดสิทธิ์

โหมดสิทธิ์ควบคุมว่า Perch จะทำงานไปได้มากแค่ไหนก่อนจะหยุดถามคุณ ตั้งค่าได้ด้วย /permission ระหว่างเซสชัน หรือ --permission ตอนเริ่มรัน

Perch ตัดสินใจเป็นสองขั้น ชุดกฎตายตัวจะทำงานก่อนในทันที การอ่านไฟล์ การแก้ไขภายในเวิร์กสเปซของคุณ และการรันคำสั่งบิลด์และเทสต์ของโปรเจกต์เองจะดำเนินไปได้เลย force push การเขียนประวัติใหม่ (history rewrite) และการลบจำนวนมากจะหยุดรอคุณเสมอ และพาธในรายการบล็อกพาธที่อ่อนไหว (คีย์ ข้อมูลรับรองตัวตน โฟลเดอร์ระบบ) จะถูกปฏิเสธในทุกโหมด สิ่งที่เหลือคือการกระทำที่มีผลตามมาชุดที่เล็กกว่าซึ่งกฎเหล่านั้นตัดสินเองไม่ได้ และวิธีจัดการกับส่วนที่เหลือนี้คือสิ่งที่ทำให้แต่ละโหมดต่างกัน

โหมด	สิ่งที่รันได้โดยไม่ต้องถาม
Default	อ่านเท่านั้น การเขียน คำสั่ง การส่ง และการลบทุกครั้งจะถามคุณก่อน
Auto Review	งานความเสี่ยงต่ำและปานกลางที่ย้อนกลับได้จะรันเอง การกระทำที่มีผลตามมาแต่ละครั้งที่เกินกว่านั้นจะถูกตรวจโดยผู้รีวิวที่แยกต่างหาก ซึ่งจะถามคุณก็ต่อเมื่อไม่แน่ใจ
Take the Wheel	ทุกอย่าง โดยไม่ถาม
Plan	อ่านอย่างเดียว เครื่องมือที่เปลี่ยนแปลงข้อมูลจะถูกบล็อกไว้จนกว่าคุณจะอนุมัติแผน

เริ่มแบบเข้มงวด

Default คือโหมดที่เหมาะกับงานจริง ไม่มีอะไรที่ย้อนกลับไม่ได้เกิดขึ้นโดยที่คุณไม่เห็น เปลี่ยนไปใช้ Auto Review เมื่อคุณไว้ใจลูปการทำงานสำหรับโฟลเดอร์นั้นแล้ว และเก็บ Take the Wheel ไว้ใช้กับงานที่คุณเคยเห็น Perch รันได้ถูกต้องมาแล้ว

Auto Review ตัดสินใจอย่างไร

Auto Review คือโหมดที่ปล่อยให้ทำงานเองได้ แต่ยังมีด่านกั้นอยู่หน้างานที่มีผลตามมา แทนที่จะหยุดทุกครั้งที่มีการเขียนหรือรันคำสั่ง มันจะส่งการกระทำแต่ละรายการที่กฎตายตัวตัดสินให้ผ่านไม่ได้ไปยังผู้รีวิวที่แยกต่างหาก ซึ่งจะตัดสินก่อนที่การกระทำนั้นจะรัน

การกระทำที่ได้รับอนุญาตจะรัน และเทิร์นจะดำเนินต่อไปโดยไม่ขัดจังหวะคุณ
การกระทำที่ถูกบล็อกจะไม่รัน Perch จะได้รับคำสั่งให้หาวิธีที่ปลอดภัยกว่าเพื่อไปถึงเป้าหมาย ไม่ใช่หาทางเลี่ยงการบล็อก แล้วทำงานต่อไป
Perch จะถามคุณเมื่อผู้รีวิวตัดสินไม่ได้ เมื่อการกระทำประเภทเดียวกันถูกบล็อกหลายครั้งติดต่อกัน หรือสำหรับการกระทำที่เสี่ยงที่สุดซึ่งไม่ถูกรีวิวโดยอัตโนมัติเลย ได้แก่ force push และการลบจำนวนมาก ซึ่งจะหยุดรอการยืนยันจากคุณเสมอ

ผู้รีวิวเห็นคำขอของคุณและการกระทำที่ Perch กำลังจะทำ และไม่เห็นอะไรอื่นอีก มันไม่อ่านเนื้อหาไฟล์หรือเอาต์พุตของคำสั่ง คำสั่งที่ซ่อนอยู่ในหน้าเว็บหรือเอกสารจึงโน้มน้าวให้มันอนุมัติอะไรไม่ได้ ถ้าผู้รีวิวใช้งานไม่ได้เมื่อใด Perch จะถามคุณแทนการเดา การตรวจเหล่านี้ใช้การใช้งานที่รวมอยู่ในแพ็กเกจของคุณเพียงส่วนน้อย แลกกับโหมดที่รันได้โดยไม่ต้องมีคนเฝ้า โดยไม่ได้รันแบบปิดตา

เส้นแบ่งที่ Auto Review ใช้คือย้อนกลับได้กับย้อนกลับไม่ได้ ไม่ใช่ง่ายกับยาก การแก้ไขไฟล์ที่คุณย้อนกลับได้เป็นคนละประเภทกับการส่งอีเมล และผู้รีวิวก็ปฏิบัติต่อทั้งสองอย่างตามนั้น

ระดับโมเดล

/model และ --model รับระดับของ Roost ซึ่งให้ Roost เลือกโมเดลที่มีความสามารถเหมาะกับแต่ละงาน ในอัตราการคิดค่าใช้จ่ายมาตรฐาน

auto: ให้ Roost เลือก
standard, standard max: งานประจำวัน
pro, pro max: งานที่ยากที่สุด

คุณยังปักหมุดโมเดลที่ระบุชัดเจนได้ด้วย (เช่น /model claude-opus-5.5 บน Pro หรือบิลด์เฉพาะของ GLM, Kimi, MiniMax, DeepSeek หรือ Qwen) เมื่อคุณต้องการใช้โมเดลที่รู้แน่ชัดตลอดทั้งงาน รัน /model โดยไม่ใส่อาร์กิวเมนต์เพื่อดูตัวเลือกปัจจุบันและรายชื่อทั้งหมด

ใช้โมเดลของคุณเอง

มีสองคำสั่ง ขึ้นอยู่กับว่าโมเดลรันบนเครื่องของใคร

perch byok รันเทิร์นบนคีย์คลาวด์ที่บันทึกไว้ในบัญชีของคุณ ตัวคีย์ถูกเข้ารหัสและเก็บไว้ในบัญชี คีย์ที่เพิ่มบนเว็บจึงใช้ที่นี่ได้ทันที ส่วนการเลือกใช้คีย์นั้นแยกตามแต่ละอุปกรณ์

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

คุณเพิ่มและทดสอบคีย์จากที่นี่ได้ด้วย รวมถึง endpoint ของคุณเองที่เข้ากันได้กับ 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 ชี้ Perch ไปที่โมเดลที่คุณรันเอง เช่น Ollama, LM Studio หรือ llama.cpp แทน Roost endpoint ไม่เคยออกจากเครื่องของคุณ นี่จึงเป็นเหตุผลที่คำสั่งนี้ใช้ได้เฉพาะใน 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

เทิร์นที่รันบนทั้งสองแบบจะไม่ถูกนับรวมใน Perch Token ของคุณ และ Perch จะไม่สลับไปใช้โมเดลแบบโฮสต์อย่างเงียบๆ ถ้า endpoint ของคุณล้มเหลว ดูใช้คีย์ API ของคุณเอง

เชื่อมต่อเครื่องมือ

CLI เชื่อมต่อกับเซิร์ฟเวอร์ MCP เพื่อเพิ่มความสามารถที่อยู่นอกเหนือโฟลเดอร์ คุณเพิ่มเซิร์ฟเวอร์ได้ใน .perch/mcp.json แล้วเครื่องมือที่เชื่อมต่อจะแสดงเคียงข้างเครื่องมือในตัว ดูเซิร์ฟเวอร์ MCP

เบราว์เซอร์ของเอเจนต์ ใช้ได้เฉพาะบนเดสก์ท็อป งานที่ต้องใช้เบราว์เซอร์จึงใช้ใน CLI ไม่ได้ ถ้าคุณต้องใช้งานนี้จากเวิร์กโฟลว์ที่ขับเคลื่อนด้วยเทอร์มินัล ให้รันส่วนนั้นในแอปเดสก์ท็อป

ขั้นตอนถัดไป

เพอร์โซนา

สองน้ำเสียง เอนจินเดียว เครื่องมือเดียวกันและงานเดียวกัน แต่น้ำเสียงต่างกัน

การแก้ปัญหา

ปัญหาไม่กี่อย่างที่มักเกิดขึ้น และวิธีแก้

คู่มืออ้างอิง CLI

ในหน้านี้