CLI reference

@tryorcha/cli gives people, coding agents, and CI jobs access to a workspace from a terminal. Each command sends a request to the same token-authenticated API that MCP and REST use. Authorization, folder scope, citations, and usage analytics are the same on all three. The CLI does not cache data on the local machine. The browse commands, search, memory list, memory get, and feedback only read data. sync, memory create, and memory update write data and need a token with the write permission.

npm install -g @tryorcha/cli
orcha --version

Node 20 or a newer version is necessary.

Authenticate

orcha login                        # opens the browser; you pick the workspace and permissions
orcha login --no-browser           # prints the sign-in URL instead of opening it
orcha login --token                # use an API token; prompts for it without echoing
orcha login --token orca_...       # non-interactive
orcha status                       # show base URL, credential source, and reachable workspace
orcha logout                       # remove the stored credentials

Browser login is the default. The CLI registers itself with the Orcha OAuth authorization server. The Claude and ChatGPT connectors use the same server. The CLI opens the authorize URL in the browser and listens on 127.0.0.1 for the redirect. On the consent screen, select the workspace and the permissions (read, write, or delete). Orcha limits the permissions to your workspace role and checks them on each request. The CLI stores a short-lived access token and a refresh token, and it renews the session automatically. If you do not use the refresh token for seven days, it expires. Then run orcha login again. To revoke a browser login, open the MCP settings page in the app and revoke "Orcha CLI".

API tokens are the correct choice for CI, agent sandboxes, and other unattended jobs. A token does not expire unless you set an expiry date. You can limit a token to specified folders. login --token rejects a value that does not start with orca_. It also makes a live request before it saves the token, so the CLI does not save a token with a typing error. If you paste the token at the prompt, the CLI does not show it on the screen.

The CLI writes the credentials to ~/.config/orcha/config.json with 0600 permissions. If $XDG_CONFIG_HOME is set, the CLI uses that directory.

The CLI resolves the credentials and the endpoint in this order:

The default base URL is https://app.tryorcha.com.

Browse the workspace

The CLI shows the workspace as a read-only tree with four directories: /files, /memories, /databases, and /sources. The root README.md describes each directory.

orcha cat /README.md                    # start here
orcha ls -l /files                      # sizes, updated dates, useWhen hints
orcha tree -L 2 /files
orcha find /files -name '*.md'
orcha cat -n /files/Guides/api.md
orcha rg -i "rate limit" /files
orcha head -n 40 /files/Guides/api.md
orcha wc -l /files/Guides/api.md
orcha stat /files/Guides/api.md         # entity ID, deep link, citation, freshness

The available commands are pwd, ls, tree, find, cat, grep, rg, head, tail, wc, and stat. The CLI quotes the arguments before it sends them to the restricted parser on the server.

rg searches subdirectories and shows line numbers by default. grep searches subdirectories only with -r. Patterns use the RE2 syntax. RE2 does not support lookahead, lookbehind, or backreferences. If a pattern uses one of these, the server returns an error that names the construct. Use -F to match the pattern as literal text.

Run a script

exec sends a full script, with pipes and chains, in one request:

orcha exec "rg -i 'rate limit' /files | head -20"
orcha exec "ls /memories && cat /memories/onboarding/README.md"

You can pipe output into grep, rg, head, tail, and wc. You can chain commands with ; and &&. The server rejects redirection, command substitution, and commands that are not in the list. The server limits each execution with a scan budget. If the budget is exhausted, the CLI prints [scan budget exhausted: ...] on stderr. This message tells you that the output is not complete.

Search

orcha search "how do we enforce plan limits"
orcha search "deployment requirements" --limit 5

search runs the same hybrid retrieval as search_context. It prints the results in rank order, with titles, locations, and deep links. --limit accepts a value from 1 to 50. The default is 10. Use search for questions about meaning. Use the browse commands for questions about structure. The API gives more settings for search. The search guide describes them.

Memories

A memory is a curated set of context. An agent loads the full set instead of a search. To read memories, the token needs the read permission. To create and update memories, the token needs the write permission. To remove a member, the token needs the delete permission.

orcha memory list
orcha memory get deployment-runbook
orcha memory create --name "Deployment runbook" \
  --use-when "Before planning or debugging a production deploy" \
  --member file:1f0e... --member folder:9c2a... --member database:5b7d...
orcha memory update deployment-runbook --use-when "Any production deploy work" \
  --add-member source-document:88ab... --remove-member 3d41...

list prints the slug, the member count, the version, and the useWhen guidance of each memory. get prints the resolved contents: file bodies, the files in folder members, the retained bodies of synced documents, and database records. After the contents, it prints coverage notes for each member that was excluded, truncated, or unavailable.

The member kinds are file, folder, source-document, and database. Each member refers to an id in the workspace. orcha memory get <slug> --json shows the member ids that you can remove. A folder member expands to the current files in the folder each time the memory loads. Thus a folder member is never stale.

Sync a local directory

orcha sync                     # sync the current directory
orcha sync ~/notes             # sync somewhere else
orcha sync ~/notes --dry-run   # show what would change, write nothing

sync reads a directory, uploads the text files, and compares them with the files that earlier runs from the same directory created in the workspace. It needs a workspace-wide token with the write permission. The server rejects folder-scoped tokens.

What gets sent

The CLI sends files with a text extension: .md, .markdown, .mdx, .txt, .text, .json, .yaml, .yml, .csv, .tsv, .rst, .org, and .adoc. The CLI does not upload other files. It counts them as skipped.

The CLI always skips hidden entries (names that start with a dot) and symbolic links. Thus .git, .env, .obsidian, and .DS_Store stay out without configuration. The CLI does not enter node_modules, __pycache__, or venv.

An .orchaignore file at the sync root excludes more files. It uses a subset of the gitignore syntax:

drafts/          # a directory anywhere, by name
*.csv            # a basename glob; * never crosses a slash
docs/scratch     # a path relative to the sync root, and everything under it
notes.txt        # any file with that name, at any depth

The CLI ignores blank lines and # comments. Negation (!) and ** are not supported.

The CLI skips a file larger than 5 MB and names it on stderr. If a run contains more than 24 MB of text, the CLI stops with an error before it uploads. If this occurs, divide the directory or add an .orchaignore file. The server accepts a maximum of 5,000 documents in one run.

Sync identity

The first run writes .orcha/sync.json with a generated name, for example notes-4f2a1c. The name comes from the directory name. Later runs use the name to find the files that they created. If you keep the file with the content, a second machine can sync into the same files. Without the file, the second machine creates a parallel tree. Use --name team-notes to set the name yourself. The CLI writes the value to the same file.

Re-running

A repeat run is safe. The CLI skips unchanged files and updates changed files. Files that are no longer in the local directory move to trash. Use --no-prune to keep them in Orcha. In both cases, the CLI lists the files that a prune would remove before it does the prune.

--conflicts sets the action for a file that already exists in Orcha:

Each run ends with a one-line result and the warnings, if there are any:

Sync complete: created 12, updated 3, unchanged 240, conflicts 1, pruned 2

--dry-run stops after the preview. It reports the counts and the prune list, writes nothing, and discards the preview run. Completed runs appear in the import history in the web app. You can roll back a run for 7 days. A rollback restores pruned files from trash and reverts the updates. The /api/v1/sync endpoints give other clients the same function.

Send feedback

orcha feedback "The deploy runbook is missing the rollback step"
orcha feedback "Search returns the 2024 pricing page first" --category wrong_result

Agents and people can report problems with the context from the terminal. The categories are missing_context, stale_content, wrong_result, tool_problem, and other. The message goes to the workspace team by email and Discord. Orcha stores only a telemetry event.

Global flags

You can put the two flags before or after the subcommand.

orcha --cite exec "rg -i 'retention' /files | head"
orcha search "billing model" --json | jq '.results[0].citation'

Exit codes

If the work fails, the CLI exits with a non-zero code. Scripts and agents can branch on the code instead of the text.

A script failure follows the bash rules. With ;, the status is the status of the last command. With &&, a failure stops the chain and the status is the failure. Authentication and transport problems have their own messages. A rejected token reports 401. A path that is out of scope, or a permission that the token does not have, reports 403. An exhausted rate limit reports 429.

Use it in CI and agents

Set the token in the environment. Then login is not necessary:

export ORCHA_TOKEN=orca_...
orcha exec "rg -i 'TODO' /files | head -20"

Give the token only the permissions that the job needs. If the job must see only one part of the workspace, limit the token to those folders. A folder-scoped token sees a pruned /files tree. Paths that are out of scope do not exist in the tree. See Tokens and scoping.

orcha agent-setup prints a block for CLAUDE.md or AGENTS.md. The block tells a coding agent the layout, the commands, and when search is better than the browse commands:

orcha agent-setup >> CLAUDE.md

REST and MCP give access to the same virtual filesystem. Browse context like a filesystem compares the three entry points.