CLI reference
Install, authenticate, and use the orcha command line client for browsing, search, directory sync, and feedback.
@tryorcha/cli gives people, coding agents, and CI access to a workspace from a terminal. Every command forwards to the same token-authenticated API as MCP and REST, so authorization, folder scoping, citations, and usage analytics behave identically. Nothing is cached locally. Browsing, search, and feedback only read; sync is the one command that writes, and it needs a token with write permission.
Node 20 or newer is required.
Authenticate
login rejects anything that does not start with orca_ and makes a live call before saving, so a typo never gets persisted. The token is written to ~/.config/orcha/config.json with 0600 permissions ($XDG_CONFIG_HOME is respected).
Credentials and the endpoint resolve in this order:
| Source | Sets | Use it for |
|---|---|---|
ORCHA_TOKEN, ORCHA_BASE_URL environment variables | token, base URL | CI and agent sandboxes |
.orcha/config.json, found by walking up from the working directory | base URL (and token, though a token does not belong in a repo) | pinning a project to one workspace |
~/.config/orcha/config.json, written by orcha login | token, base URL | everyday local use |
The base URL defaults to https://app.tryorcha.com.
Browse the workspace
The workspace mounts as a read-only tree: /files, /memories, /databases, and /sources. A root README.md explains what is mounted.
Available commands are pwd, ls, tree, find, cat, grep, rg, head, tail, wc, and stat. Arguments are quoted for you before they reach the server's restricted parser.
rg is recursive with line numbers by default; grep needs -r to descend. Patterns use RE2, so lookahead, lookbehind, and backreferences return an error naming the unsupported construct. Pass -F to match literally.
Run a script
exec takes a full script, with pipes and chaining, in one round trip:
Pipe into grep, rg, head, tail, and wc; chain with ; and &&. Redirection, command substitution, and any command outside the list are rejected. Executions are bounded by a server-side scan budget; when it trips, the CLI prints [scan budget exhausted: ...] on stderr so a truncated result is never mistaken for a complete one.
Search
This runs the same hybrid retrieval as search_context, printing ranked results with titles, locations, and deep links. --limit accepts 1 to 50 (default 10). Use search for semantic questions and the browse commands for structural ones; the search guide covers the tuning knobs available through the API.
Memories
Memories are curated context sets an agent loads whole instead of searching. Reading needs read permission; creating and updating need write; removing members needs delete.
list prints each memory's slug, member count, version, and useWhen guidance. get prints the resolved contents: file bodies, folder expansions, retained synced-document bodies, and database records, followed by coverage notes for anything excluded, truncated, or unavailable.
Member kinds are file, folder, source-document, and database, each referencing an id from the workspace (orcha memory get <slug> --json shows member ids for removal). Folders expand to their current files every time the memory loads, so a folder member never goes stale.
Sync a local directory
sync walks a directory, uploads its text files, and reconciles them against what earlier runs from the same directory put in the workspace. It needs a workspace-wide token with write permission; folder-scoped tokens are rejected.
What gets sent
Files with a text extension: .md, .markdown, .mdx, .txt, .text, .json, .yaml, .yml, .csv, .tsv, .rst, .org, and .adoc. Anything else is counted as skipped instead of uploaded.
Hidden entries (anything with a leading dot) and symlinks are always skipped, which keeps .git, .env, .obsidian, and .DS_Store out without any configuration. node_modules, __pycache__, and venv are never descended into.
An .orchaignore file at the sync root excludes more, using a subset of gitignore syntax:
Blank lines and # comments are ignored. Negation (!) and ** are not supported.
A file over 5 MB is skipped and named on stderr. A run carrying more than 24 MB of text stops with an error before anything uploads, so split the directory or add an .orchaignore. The server caps a run at 5,000 documents.
Sync identity
The first run writes .orcha/sync.json with a generated name like notes-4f2a1c, based on the directory name. That name is how later runs find what they created, so keeping the file next to the content lets a second machine reconcile into the same files instead of building a parallel tree. Pass --name team-notes to set it yourself; the value is written back to the same file.
Re-running
Re-running is safe. Unchanged files are skipped, changed files are updated, and files that disappeared locally move to trash. Pass --no-prune to leave them in Orcha; either way the CLI lists what a prune would take before it acts.
--conflicts decides what happens when a file already exists in Orcha:
| Policy | Effect |
|---|---|
update (default) | Apply the local version, except where the file was edited in Orcha since the last sync; those are left alone and counted as conflicts |
skip | Leave every file that already exists in Orcha untouched |
duplicate | Write the local version alongside the existing Orcha copy |
Each run ends with a one-line outcome, plus any warnings:
--dry-run stops after the preview: it reports the counts and the prune list, writes nothing, and discards the preview run. Completed runs show up in the web app's import history and can be rolled back for 7 days, which restores pruned files from trash and reverts updates. The /api/v1/sync endpoints expose the same work to clients other than the CLI.
Send feedback
Agents and people can report context problems without leaving the terminal. Categories are missing_context, stale_content, wrong_result, tool_problem, and other. The message reaches the workspace team by email and Discord; nothing is stored beyond a telemetry event.
Global flags
Both work before or after the subcommand.
| Flag | Effect |
|---|---|
--cite | Append a citations block: path, title, deep link, and freshness for every file whose content was returned |
--json | Print the raw API response instead of formatted output |
Exit codes
The CLI exits non-zero when the work failed, so scripts and agents can branch on status instead of parsing text.
| Code | Meaning |
|---|---|
0 | Success |
1 | The script failed (missing path, unsupported pattern, budget abort), or the request was rejected |
Script failure follows bash semantics: ; takes the status of whatever ran last, while && preserves a short-circuited failure. Authentication and transport problems get their own messages: a rejected token reports 401, an out-of-scope path or missing permission reports 403, and exhausting a rate limit reports 429.
Use it in CI and agents
Set the token in the environment and skip login:
Give the token only the permissions the job needs, and folder-scope it when a job should see one slice of the workspace. A folder-scoped token sees a pruned /files tree where out-of-scope paths simply do not exist. See Tokens and scoping.
orcha agent-setup prints a ready-made block for CLAUDE.md or AGENTS.md that teaches a coding agent the layout, the commands, and when to prefer search over browsing:
The same virtual filesystem is reachable over REST and MCP; Browse context like a filesystem compares the three entry points.