Orca CLI reference

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

CLI orca nói chuyện với một runtime Orca đang chạy. Dùng nó khi một shell script hoặc agent cần kiểm tra worktree, khởi chạy terminal, mở file, tự động hoá trình duyệt built-in, hoặc báo cáo tiến độ ngược lại vào Orca.

Xác minh runtime

Đăng ký CLI ở Settings → Experimental → CLI, rồi kiểm tra xem nó có tới được Orca không:

command -v orca
orca status --json

Nếu Orca chưa chạy sẵn:

orca open --json
orca status --json

Dùng --json khi một tool khác sẽ parse kết quả. Output đọc được cho người chỉ dành cho kiểm tra nhanh trên terminal.

Selector

Hầu hết lệnh chấp nhận selector thay vì bắt buộc ID dài:

orca repo show --repo id:<repoId> --json
orca worktree show --worktree active --json
orca worktree show --worktree path:/abs/path/to/worktree --json
orca worktree show --worktree branch:feature-name --json
orca worktree show --worktree issue:123 --json

active và current resolve thành worktree Orca-managed bao quanh thư mục hiện tại của shell hoặc context terminal. Dùng selector tường minh trong script có thể chạy ngoài worktree đích. Với runtime remote, ưu tiên selector đầy đủ phía server như id:<repoId>::<absolute-worktree-path> hoặc path:<absolute-server-path> vì thư mục hiện tại của shell local có thể không tồn tại trên host runtime.

Lệnh runtime

orca open --json
orca status --json
orca serve --port 6768 --pairing-address 100.64.1.20 --json

orca serve khởi động một runtime server ở foreground mà không mở cửa sổ desktop. Dùng nó cho Remote Orca Server hoặc môi trường headless, và dừng bằng Ctrl-C.

Repo

orca repo list --json
orca repo add --path /abs/path/to/repo --json
orca repo show --repo id:<repoId> --json
orca repo set-base-ref --repo id:<repoId> --ref origin/main --json
orca repo search-refs --repo id:<repoId> --query main --limit 10 --json

Đặt base ref của repo trước khi tạo nhiều worktree, để task mới mặc định branch đúng chỗ.

Worktree

orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree active --json
orca worktree create --repo id:<repoId> --name fix-login --json
orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
orca worktree rm --worktree id:<worktreeId> --force --json

Khi worktree create chạy từ bên trong một worktree Orca-managed, Orca ghi worktree mới là con nếu suy luận được quan hệ đó. Truyền --parent-worktree active để nói rõ, hoặc --no-parent khi công việc mới độc lập.

Flag khởi động agent:

orca worktree create --name review-api --agent claude --setup run --json
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
orca worktree create --name hidden-setup --setup inherit --json

--agent khởi chạy agent đã chọn trong terminal đầu tiên. --prompt gửi công việc ban đầu cho agent đó. --setup run|skip|inherit điều khiển hook setup repo; inherit theo policy của repo.

Terminal

orca terminal list --worktree active --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "runner" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json

Bỏ --terminal để nhắm vào terminal đang active trong worktree hiện tại. Đọc trước khi gửi khi bạn không chắc terminal đang chờ gì.

Với output dài, dùng đọc theo cursor. Lưu nextCursor từ một lần đọc, rồi truyền lại bằng --cursor để chỉ lấy output mới.

File

orca file open src/App.tsx --worktree active --json
orca file diff src/App.tsx --staged --worktree active --json
orca file open-changed --mode both --worktree active --json

Đường dẫn tương đối với worktree đã chọn. open-changed đọc git status và mở file đã thay đổi ở chế độ edit, diff, hoặc cả hai.

Trình duyệt built-in

Lệnh browser điều khiển tab trình duyệt nhúng của Orca cho worktree đã chọn. Chúng không điều khiển Chrome, Safari, hay UI desktop của Orca.

Dùng vòng lặp snapshot → hành động → snapshot lại:

orca goto --url http://localhost:3000 --worktree active --json
orca snapshot --worktree active --json
orca click --element @e3 --worktree active --json
orca fill --element @e1 --value "test@example.com" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json

Ref như @e3 đến từ snapshot. Snapshot lại sau khi điều hướng, chuyển tab, click làm đổi trang, và bất kỳ lỗi ref-đã-cũ nào.

Lệnh tab và capture:

orca tab list --worktree active --json
orca tab create --url http://localhost:3000 --worktree active --json
orca tab switch --index 1 --worktree active --json
orca capture start --worktree active --json
orca console --limit 50 --worktree active --json
orca network --limit 50 --worktree active --json
orca full-screenshot --worktree active --json
orca pdf --worktree active --json

Dùng orca exec --command "<agent-browser command>" --json chỉ cho các hành động browser chưa có lệnh Orca định kiểu riêng.

Giả lập device trên trình duyệt:

orca set device --name "iPhone 12" --worktree active --json
orca screenshot --worktree active --json

Computer use trên desktop

Dùng orca computer cho app desktop native ngoài trình duyệt built-in:

orca computer permissions --json
orca computer list-apps --json
orca computer get-app-state --app com.apple.Safari --json
orca computer click --app com.apple.Safari --element-index 12 --json
orca computer paste-text --app com.apple.Safari --text "hello" --json

Xem Computer use để biết luồng đầy đủ và cách thiết lập quyền.

Mobile emulator

Lệnh mobile emulator điều khiển thiết bị iOS Simulator qua cầu nối giới hạn theo worktree của Orca. Dùng chúng thay vì serve-sim hay simctl thô khi agent đang thao tác từ bên trong Orca, để vòng đời và state device active gắn liền với worktree hiện tại.

orca emulator list --worktree active --json
orca emulator attach "<device-name-or-udid>" --worktree active --json
orca emulator tap 0.5 0.7 --worktree active --json
orca emulator type "hello" --worktree active --json
orca emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
orca emulator button home --worktree active --json
orca emulator rotate landscape_left --worktree active --json
orca emulator exec --command "tap 0.5 0.7" --worktree active --json
orca emulator kill --worktree active --json
orca emulator shutdown --worktree active --json

Toạ độ được chuẩn hoá từ 0 đến 1. Ưu tiên tap cho các cú chạm đơn, và dùng gesture cho thao tác kéo hoặc chạm nhiều bước. Truyền --device <udid-or-name> hoặc --emulator <id> khi một script cần nhắm vào một simulator cụ thể thay vì emulator active của worktree.

Linear

Bề mặt orca linear là thứ agent dùng qua skill orca-linear (tên cài cũ linear-tickets vẫn còn hoạt động). Ưu tiên --json. Worktree đã liên kết resolve bằng --current.

Đọc

orca linear issue --current --full --json
orca linear issue ENG-123 --comments --children --relations --activity --json
orca linear search "auth bug" --workspace all --json
orca linear list --filter assigned --limit 10 --json
orca linear list-issues --team ENG --state started --assignee me --json
orca linear list-issues --query auth --updated-at -P7D --cursor <cursor> --workspace <id> --json
orca linear team list --json
orca linear team states --team ENG --json
orca linear team labels --team ENG --json
orca linear project list --query launch --json

--full mở rộng comment, children, attachment, relation, và activity. Các flag theo mục (--comments, --children, --attachments, --relations, --activity) hoạt động riêng lẻ.

Ghi kiểu MCP

# Tạo hoặc cập nhật (bỏ id/--current để tạo; cần --team và --title khi tạo)
orca linear save-issue --team ENG --title "Fix auth" --priority high --json
orca linear save-issue ENG-123 --state "In Progress" --assignee me --json
orca linear save-issue --current --project null --due-date null --json

orca linear relation add ENG-1 --related ENG-2 --type blocks --json
orca linear relation remove ENG-1 --related ENG-2 --type related --json

Label trong save-issue thay thế toàn bộ tập label (đúng ngữ nghĩa save_issue của Linear MCP). null trần sẽ xóa assignee, estimate, due date, project, hoặc parent.

Field helper (vẫn còn dùng được)

orca linear status set --current --to "In Progress" --json
orca linear assignee set --current --me --json
orca linear priority set ENG-123 --to high --json
orca linear estimate set --current --to 3 --json
orca linear due-date set --current --to 2026-08-01 --json
orca linear label add --current --label backend --json
orca linear comment add --current --body "Investigating regression" --json
orca linear attach --current --url https://example.com/repro --title "Repro" --json
orca linear create --title "Flaky login test" --team ENG --priority high --json

Chạy orca linear --help hoặc orca skills get orca-linear để xem danh sách khớp đúng phiên bản. Truyền một issue id tường minh (ví dụ ENG-123) khi script có thể chạy ngoài một worktree đã liên kết Orca.

Skills (local, không cần runtime)

Liệt kê guide có sẵn, in ra một guide khớp phiên bản, hoặc cài/cập nhật gói skill hybrid mà không cần Settings UI desktop:

orca skills list
orca skills get orca-cli
orca skills get orchestration --full
orca skills install --skill orca-cli --skill orchestration
orca skills install --all --dry-run
orca skills update --all

install / update gọi ra cùng lệnh npx skills mà Settings dùng. Chúng không liên hệ tới runtime Orca. Xem Orca skills.

Account (runtime local trên host)

Trên một host headless chạy Orca (orca serve hoặc app desktop), thêm tài khoản Claude/Codex được quản lý khi client remote không dùng được Add account (phạm vi runtime remote tắt nút đó):

orca account list
orca account add # Claude mặc định
orca account add --agent codex

account add chạy claude login / codex login ngay trong terminal này trên host, rồi đăng ký credential đã bắt được với runtime local. Codex dùng device authorization nên trình duyệt có thể hoàn tất trên một máy khác. Chạy các lệnh này trên chính máy sở hữu tài khoản - không phải qua một session remote chỉ-client.

Artifact

Publish HTML hoặc Markdown qua tài khoản Orca đã đăng nhập. Xem một link công khai không cần đăng nhập; tạo/list/update/delete thì cần. Publish mặc định tắt - một người phải bật Settings → Artifacts → Allow publishing public artifact links trên thiết bị. Không có flag CLI nào mở cổng này. list, unshare, và delete vẫn khả dụng để bạn audit hoặc thu hồi link sau khi tắt publish.

orca artifacts share ./report.html --json
orca artifacts share ./notes.md --json
orca artifacts update ./notes.md --json
orca artifacts unshare ./notes.md --json
orca artifacts list --json
orca artifacts list --cursor <cursor> --json
orca artifacts delete <id> --json

File được chấp nhận: .html, .htm, .md, .markdown.
share lưu edit token trong profile Orca đang active và không in ra nó. update / unshare resolve theo cùng đường dẫn local và profile đã share file đó ban đầu.
list phân trang (nextCursor → --cursor). delete nhận artifact id từ list và không cần file gốc.
Asset HTML dạng tương đối không được upload - chia sẻ HTML tự chứa hoặc dùng URL asset tuyệt đối.
Publish/update bị từ chối sẽ fail với artifact_sharing_disabled; sửa trong Settings thay vì thử lại.
Desktop: mở một file HTML hoặc Markdown local và dùng Share as artifact, hoặc quản lý link từ trang sidebar Artifacts.

Automation, environment, và hook

Prompt theo lịch:

orca automations list --json
orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --disabled --json
orca automations run <automationId> --json

Environment runtime remote:

orca environment add --name work-laptop --pairing-code "orca://pair?code=..." --json
orca environment list --json
orca environment rm --environment <selector> --json

Hook trạng thái agent:

orca agent hooks status --json
orca agent hooks on --json
orca agent hooks off --json

Thói quen tốt cho agent

Ưu tiên --json cho các lệnh gọi tự động và từ agent.
Ưu tiên selector hơn là parse nhãn UI.
Đọc trạng thái terminal trước khi gửi input, trừ khi input tiếp theo đã rõ ràng.
Dùng comment worktree cho các checkpoint tiến độ. Xem Worktree checkpoint.
Dùng Orchestration cho các dispatch đa agent cần theo dõi, thay vì prompt terminal tự phát.

Phuc Tran

Software Engineer | Learning Claude