Tài liệu tham khảo CLI
Mọi lệnh trong Perch CLI, gồm các lệnh con perch bạn chạy từ shell và các lệnh gạch chéo bạn dùng trong phiên tương tác.
Perch CLI là operator đầy đủ trong terminal của bạn. CLI chạy cùng bộ máy và trình kiểm tra trích dẫn như ứng dụng máy tính, làm việc từ thư mục bạn đang ở. Trang này là tài liệu tham khảo lệnh đầy đủ: các lệnh con perch bạn chạy từ shell, các cờ toàn cục định hình phiên và các lệnh gạch chéo bạn nhập khi Perch đang chạy.
Cài đặt và đăng nhập
npm install -g perchai-cli # Node 18+
perch login # opens a browser tab, saves your session
perch # start working in the current folderHai cách chạy
Có hai chế độ, khác nhau ở việc bạn ở lại trong phiên hay chạy một tác vụ rồi thoát.
- Tương tác. Chạy
perchkhông có đối số để mở trò chuyện trong thư mục hiện tại. Perch đọc các tệp ở đó, nhận tác vụ bằng ngôn ngữ thông thường và duy trì luồng hội thoại. Các lệnh gạch chéo bên dưới định hướng Perch trong lúc làm việc. - Chạy một lần. Chạy
perch run "<task>"để thực hiện một tác vụ rồi trả về. Thêm--jsonđể có đầu ra máy có thể đọc. Đây là dạng dùng trong script hoặc đường ống.
perch # interactive session in .
perch run "Check March invoices for duplicates." # one task, then exit
perch run "Draft the venue section" --persona quill --jsonLệnh shell
Các lệnh bạn chạy từ shell dưới dạng perch <command>.
| Lệnh | Chức năng |
|---|---|
perch | Mở trò chuyện Perch tương tác trong thư mục hiện tại. |
perch login | Mở trang đăng nhập trên trình duyệt và lưu phiên của terminal này. |
perch status | Hiển thị trạng thái xác thực đã lưu và kết nối ứng dụng. |
perch logout | Xóa phiên xác thực CLI đã lưu. |
perch skills [name] | Liệt kê các skill cốt lõi của Perch hoặc in nội dung một skill. |
perch run "<task>" | Chạy một tác vụ bằng ngôn ngữ tự nhiên qua operator. |
perch ap evidence <folder> | Chuẩn bị bằng chứng kiểm toán AP, hồ sơ, số liệu và artifact đồ thị. |
perch ap packet <folder> | Tạo bộ hồ sơ và báo cáo kiểm toán AP đầy đủ. |
perch test ap <folder> | Chạy bằng chứng + bộ hồ sơ và xuất bản ghi đạt/không đạt. |
perch byok use <provider> | off | Chạy các lượt của terminal này bằng khóa đám mây đã lưu vào tài khoản hoặc quay lại Perch. |
perch byok list | status | test | set | remove | Quản lý khóa trong tài khoản mà không rời terminal. |
perch byolm set <url> <model> | Trỏ Perch đến mô hình cục bộ của bạn (Ollama, LM Studio, llama.cpp). |
perch byolm status | clear | test | Hiển thị, xóa hoặc thử mô hình cục bộ. |
Cờ toàn cục
Các cờ này định hình phiên và có thể truyền cho perch hoặc perch run:
| Cờ | Giá trị | Mục đích |
|---|---|---|
--cwd <dir> | đường dẫn bất kỳ | Làm việc từ thư mục khác với thư mục hiện tại. |
--permission <mode> | default, auto_review, take_the_wheel, plan | Đặt mức độ Perch có thể làm mà không cần hỏi. Xem Chế độ quyền hạn. |
--mode <mode> | ask, agents, plan | Đặt chế độ trò chuyện cho phiên. |
--persona <persona> | saffron, quill | Bắt đầu với một giọng văn. Xem Persona. |
--model <tier> | standard, standard max, pro, pro max | Ghim cấp Roost cho lần chạy. |
--thinking <on|off> | on, off | Bật/tắt suy nghĩ mở rộng cho mô hình đã chọn. |
--thread <id> | mã định danh luồng hội thoại | Tiếp tục một luồng hội thoại cụ thể (với perch run). |
--json | Không có | Xuất đầu ra máy có thể đọc (với perch run). |
Lệnh gạch chéo
Khi ở trong phiên tương tác, nhập lệnh gạch chéo tại prompt. Trong lúc Perch làm việc, bạn cũng có thể nhập nội dung định hướng và nhấn Enter; Ctrl-C dừng lượt hiện tại và Ctrl-E mở rộng chi tiết.
Phần này liệt kê các lệnh. Để biết khi nào nên dùng từng lệnh và kết quả nhận được, xem Lệnh gạch chéo.
Thực hiện công việc
| Lệnh | Chức năng |
|---|---|
/goal <objective> | Tự chủ thực hiện mục tiêu qua nhiều lượt cho đến khi kiểm tra hoàn tất đạt yêu cầu. |
/goal [status|pause|resume|clear] | Kiểm tra hoặc điều khiển mục tiêu đang hoạt động. Mục tiêu vẫn được giữ khi thoát, nên /goal resume hoạt động trong phiên sau. |
/verify [text] | Kiểm tra lại câu trả lời cuối hoặc văn bản đã dán với các nguồn đã lập chỉ mục. |
/verify --changed | Chỉ kiểm tra lại các nhận định có nguồn thay đổi từ lần /verify trước. |
Phiên và trợ giúp
| Lệnh | Chức năng |
|---|---|
/help | Hiển thị danh sách lệnh đầy đủ. |
/status | Hiển thị cwd, xác thực, chế độ, persona, quyền hạn và luồng hội thoại. |
/context | Hiển thị thước đo ngữ cảnh và chi tiết nén ngữ cảnh. |
/clear | Xóa bộ nhớ hội thoại cục bộ của phiên terminal này. |
/exit | Thoát Perch CLI. |
Tài khoản
| Lệnh | Chức năng |
|---|---|
/login | Đăng nhập qua OAuth trên trình duyệt. |
/logout | Xóa thông tin xác thực CLI đã lưu. |
Định hướng công việc
| Lệnh | Chức năng |
|---|---|
/persona [saffron|quill] | Hiển thị hoặc đổi giọng văn. Persona. |
/mode [ask|agents|plan] | Hiển thị hoặc đặt chế độ trò chuyện. |
/permission [mode] | Hiển thị hoặc đặt mức tự chủ cho các lượt tiếp theo. Chế độ quyền hạn. |
/model [tier|name] | Hiển thị hoặc đặt mô hình: cấp Roost hoặc ghim mô hình cụ thể. Cấp mô hình. |
/thinking [on|off] | Hiển thị hoặc bật/tắt suy nghĩ mở rộng cho mô hình đã chọn. |
/byok [provider|off] | Hiển thị hoặc đổi khóa đám mây đã lưu dùng cho các lượt của terminal này. Dùng khóa API của riêng bạn. |
/local-tools [on|off] | Hiển thị hoặc bật/tắt các công cụ shell và tệp cục bộ. |
/cwd [dir] | Hiển thị hoặc đổi thư mục làm việc. |
/thread [new|id] | Hiển thị, đặt lại hoặc đặt mã định danh luồng hội thoại hiện tại. |
/permissions là bí danh
/permissions thực hiện cùng chức năng như /permission; cả hai cách viết đều hoạt động.Bộ nhớ, mức sử dụng và skill
| Lệnh | Chức năng |
|---|---|
/memory-audit <text> | Kiểm tra liệu một ghi chú có được lưu vào bộ nhớ hay không và vì sao. Bộ nhớ. |
/usage | Hiển thị mức Perch Token đi kèm và mức sử dụng của phiên này. |
/skills [name] | Liệt kê các skill cốt lõi của Perch hoặc hiển thị nội dung một skill. |
Giao việc
| Lệnh | Chức năng |
|---|---|
/delegate <task> | Giao tác vụ có phạm vi xác định cho agent chạy nền để thực hiện bất đồng bộ và xem xét kết quả. |
/bg <task> | Cách viết ngắn của /delegate. |
Dùng /delegate khi tác vụ độc lập và bạn muốn tiếp tục làm việc thay vì theo dõi quá trình chạy. Agent thực hiện trong nền và trả về kết quả để xem xét, nên công việc dài không bao giờ chặn phiên.
Chế độ quyền hạn
Chế độ quyền hạn kiểm soát mức độ Perch thực hiện trước khi dừng lại để hỏi. Đặt chế độ bằng /permission trong phiên hoặc --permission khi khởi chạy.
Perch quyết định theo hai bước. Một bộ quy tắc cố định chạy trước, ngay lập tức: đọc tệp, chỉnh sửa trong không gian làm việc và chạy các lệnh build và kiểm thử của chính dự án được thực hiện ngay; đẩy cưỡng bức, viết lại lịch sử và xóa hàng loạt luôn dừng để hỏi bạn; danh sách chặn đường dẫn nhạy cảm (khóa, thông tin xác thực, thư mục hệ thống) bị từ chối ở mọi chế độ. Phần còn lại là nhóm nhỏ hơn gồm các hành động có hệ quả mà những quy tắc đó không thể tự quyết định, và cách xử lý phần còn lại này tạo nên sự khác biệt giữa các chế độ.
| Chế độ | Những gì chạy mà không hỏi |
|---|---|
| Default | Chỉ đọc. Mọi thao tác ghi, lệnh, gửi và xóa đều hỏi bạn trước. |
| Auto Review | Công việc có thể hoàn tác với rủi ro thấp và trung bình tự chạy. Mỗi hành động có hệ quả ngoài phạm vi đó được một bên đánh giá riêng kiểm tra, chỉ hỏi bạn khi không chắc chắn. |
| Take the Wheel | Mọi thứ, không hỏi. |
| Plan | Chỉ đọc. Các công cụ thay đổi dữ liệu vẫn bị chặn cho đến khi bạn phê duyệt kế hoạch. |
Bắt đầu nghiêm ngặt
Cách Auto Review quyết định
Auto Review là chế độ không cần bạn giám sát mà vẫn có bước bảo vệ trước công việc có hệ quả. Thay vì tạm dừng ở mọi thao tác ghi hoặc lệnh, nó gửi từng hành động mà quy tắc cố định chưa cho phép đến một bên đánh giá riêng, đưa ra quyết định trước khi hành động chạy:
- Hành động Allowed được chạy và lượt tiếp tục mà không làm gián đoạn bạn.
- Hành động Blocked không chạy. Perch được yêu cầu tìm cách an toàn hơn để đạt mục tiêu, không tìm cách vượt qua việc chặn, và tiếp tục làm việc.
- Perch hỏi bạn khi bên đánh giá không thể quyết định, khi cùng loại hành động bị chặn nhiều lần liên tiếp hoặc với các hành động rủi ro cao nhất không bao giờ được đánh giá tự động: đẩy cưỡng bức và xóa hàng loạt luôn dừng để bạn xác nhận.
Bên đánh giá chỉ thấy yêu cầu của bạn và hành động Perch sắp thực hiện, không thấy gì khác. Nó không đọc nội dung tệp hay đầu ra lệnh, nên chỉ dẫn ẩn trong trang web hoặc tài liệu không thể thuyết phục nó phê duyệt điều gì đó. Nếu bên đánh giá không khả dụng, Perch hỏi bạn thay vì đoán. Các bước kiểm tra này dùng một phần nhỏ mức sử dụng đi kèm để đổi lấy chế độ chạy không cần giám sát nhưng vẫn có kiểm soát.
Ranh giới Auto Review đặt ra là giữa có thể hoàn tác và không thể hoàn tác, không phải giữa dễ và khó. Chỉnh sửa tệp bạn có thể hoàn tác thuộc nhóm khác với gửi email, và bên đánh giá xử lý chúng theo sự khác biệt đó.
Cấp mô hình
/model và --model nhận cấp Roost, cho phép Roost chọn mô hình đủ khả năng cho từng tác vụ theo mức phí tiêu chuẩn:
auto: để Roost chọn.standard,standard max: công việc hằng ngày.pro,pro max: các tác vụ khó nhất.
Bạn cũng có thể ghim mô hình cụ thể (ví dụ /model claude-opus-5.5 trên Pro, hoặc một bản GLM, Kimi, MiniMax, DeepSeek hay Qwen cụ thể) khi cần dùng một mô hình đã biết từ đầu đến cuối. Chạy /model không có đối số để xem lựa chọn hiện tại và danh sách đầy đủ.
Dùng mô hình của riêng bạn
Hai lệnh, tùy theo mô hình chạy trên máy của ai.
perch byok chạy các lượt bằng khóa đám mây đã lưu vào tài khoản. Bản thân khóa được lưu trên tài khoản và mã hóa, nên khóa thêm trên web đã có sẵn ở đây; lựa chọn dùng khóa là riêng cho từng thiết bị.
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 RoostBạn cũng có thể thêm và thử khóa từ đây, kể cả endpoint tương thích với OpenAI của riêng bạn:
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 openaiperch byolm trỏ Perch đến mô hình bạn tự chạy, như Ollama, LM Studio hoặc llama.cpp, thay vì Roost. Endpoint không bao giờ rời máy của bạn, nên lệnh này chỉ có trên 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 RoostCác lượt dùng một trong hai cách không được tính vào Perch Token của bạn, và Perch không âm thầm chuyển sang mô hình do Perch lưu trữ nếu endpoint gặp lỗi. Xem Dùng khóa API của riêng bạn.
Kết nối công cụ
CLI kết nối với máy chủ MCP để có các khả năng ngoài thư mục. Bạn thêm chúng trong .perch/mcp.json, rồi các công cụ đã kết nối xuất hiện cùng công cụ tích hợp. Xem Máy chủ MCP.
Trình duyệt agent chỉ có trên ứng dụng máy tính, nên công việc trình duyệt không khả dụng trong CLI. Nếu cần trong quy trình điều khiển từ terminal, chạy phần đó trong ứng dụng máy tính.
Bước tiếp theo
Lệnh gạch chéo
Cách thực sự dùng từng lệnh gạch chéo trong Perch Terminal và CLI, kết quả nhận được và khi nào nên dùng thay vì chỉ đặt câu hỏi.
Dùng khóa API của riêng bạn
Chạy Perch bằng khóa mô hình hoặc endpoint của riêng bạn, trên mọi gói kể cả gói miễn phí. Thiết lập cho Web, Desktop và CLI, cùng cách tính với mức sử dụng đi kèm.