orca/docs/orca-cli-v1-spec.md

Orca CLI V1 Spec

Goal

Define the first strict orca CLI contract for agents.

This spec focuses on:

• exact commands
• exact selector grammar
• exact handle semantics
• exact JSON contract
• what is in v1 now
• what is explicitly deferred because the current runtime does not yet support it cleanly

This document is intended to be implementation-facing.

Scope

The CLI connects to a running Orca editor.

The v1 contract is split into two buckets:

• v1-now: can be grounded in current Orca persistence and IPC behavior with limited new plumbing
• v1-runtime-layer: desirable v1 public contract, but requires a shared runtime/orchestration layer before it is safe to ship

Global Rules

Output modes

All agent-facing commands must support --json.

When --json is used:

• stdout contains exactly one JSON object
• stdout contains no progress text, logs, or prose
• stderr is reserved for failures and unexpected diagnostics
• non-zero exit code indicates command failure

Human-readable output may exist without --json, but --json is the normative contract for agents.

Metadata

All --json responses include:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "requestId": "req_123"
  }
}

Commands that depend on the live runtime layer also include:

{
  "_meta": {
    "runtimeId": "runtime_abc123"
  }
}

Errors

All failures in --json mode must return:

{
  "_meta": {
    "requestId": "req_123"
  },
  "error": {
    "code": "selector_not_found",
    "message": "No worktree matched selector \"branch:feature/foo\".",
    "retryable": false
  }
}

Minimum standard error codes:

• orca_not_running
• runtime_unavailable
• selector_not_found
• selector_ambiguous
• terminal_handle_stale
• terminal_not_found
• repo_not_found
• worktree_not_found
• not_supported_in_v1
• invalid_argument

Selectors

Selectors are command-time identifiers.

Repo selector grammar

Explicit forms:

• id:<repo-id>
• path:<absolute-path>
• name:<display-name>

Bare fallback order:

1. exact repo id match
2. exact absolute path match
3. exact display name match

If more than one repo matches a bare selector, fail with selector_ambiguous.

Worktree selector grammar

Explicit forms:

• id:<worktree-id>
• path:<absolute-path>
• branch:<branch-name>
• issue:<number>

Bare fallback order:

1. exact worktree id match
2. exact absolute path match
3. exact branch name match

If more than one worktree matches a bare selector, fail with selector_ambiguous.

issue:<number> must fail with selector_ambiguous if multiple worktrees share the same linked issue.

Terminal selector grammar

There is no durable selector for repeated live interaction in v1.

Discovery returns runtime handles. Follow-up commands use:

• --terminal <handle>

Human-friendly targeting like title:<name> may be useful later, but it is not part of the strict repeated-interaction contract.

Runtime Handles

Handles identify live terminal targets.

Rules:

• handles are opaque
• handles are scoped to a specific runtimeId
• handles are ephemeral by default
• runtime restart or renderer reload may invalidate all existing handles
• callers must reacquire handles after reconnect/reload unless the runtime explicitly guarantees continuity
• stale handles must fail with terminal_handle_stale

Example stale-handle error:

{
  "_meta": {
    "runtimeId": "runtime_new456",
    "requestId": "req_123"
  },
  "error": {
    "code": "terminal_handle_stale",
    "message": "The terminal handle is no longer valid for the current Orca runtime.",
    "retryable": true
  }
}

Commands

orca status

Purpose:

• confirm Orca is running
• return current runtime identity

Status:

• v1-runtime-layer

Example:

orca status --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "runtimeId": "runtime_abc123",
    "requestId": "req_123"
  },
  "status": {
    "running": true,
    "runtimeAvailable": true,
    "capabilities": {
      "repo": true,
      "worktree": true,
      "file": true,
      "search": true,
      "git": true,
      "gh": true,
      "terminal": false,
      "worktreePs": false
    }
  }
}

Implementation note:

• a minimal “is Orca running” probe may be possible earlier
• the strict status contract in this spec assumes the runtime layer exists and can issue a real runtimeId

orca repo list

Status:

• v1-now

orca repo list --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "requestId": "req_123"
  },
  "repos": [
    {
      "id": "repo_1",
      "path": "/abs/repo",
      "displayName": "orca",
      "worktreeBaseRef": "origin/main"
    }
  ]
}

orca repo add

Status:

• v1-now

orca repo add --path /abs/repo --json

orca repo show

Status:

• v1-now

orca repo show --repo path:/abs/repo --json

orca repo set-base-ref

Status:

• v1-now

orca repo set-base-ref --repo id:repo_1 --ref origin/main --json

orca repo search-refs

Renamed from search-base-refs for better verb consistency.

Status:

• v1-now

orca repo search-refs --repo id:repo_1 --query main --json

orca worktree list

Full listing command.

Status:

• v1-now

orca worktree list --repo id:repo_1 --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "requestId": "req_123"
  },
  "worktrees": [
    {
      "id": "repo_1::/abs/wt",
      "repoId": "repo_1",
      "path": "/abs/wt",
      "branch": "refs/heads/feature/foo",
      "displayName": "Feature Foo",
      "linkedIssue": 123,
      "comment": "parser work"
    }
  ]
}

orca worktree ps

Compact orchestration summary command.

Status:

• v1-runtime-layer

Rationale:

• desirable public contract
• requires a shared live-runtime summary service, not just persisted state

orca worktree ps --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "runtimeId": "runtime_abc123",
    "requestId": "req_123"
  },
  "worktrees": [
    {
      "id": "repo_1::/abs/wt",
      "repo": "orca",
      "branch": "feature/foo",
      "linkedIssue": 123,
      "unread": false,
      "liveTerminals": 2,
      "status": "active"
    }
  ]
}

orca worktree show

Status:

• v1-now

orca worktree show --worktree branch:feature/foo --json

Focused v1 also accepts active / current as CLI-only shortcuts for worktree selectors. The CLI resolves them from the caller's current directory and sends a path: selector to the runtime.

orca worktree current

Status:

• v1-now

orca worktree current --json

orca worktree create

Status:

• v1-now

This must preserve current editor behavior:

• sanitize name
• compute branch name from settings
• reject branch conflicts
• best-effort reject historical PR head-name reuse
• compute path under workspace root
• use chosen/default base ref
• create worktree
• best-effort apply linked issue/comment metadata

orca worktree create --repo path:/abs/repo --name feature-foo --issue 123 --comment "parser work" --json

orca worktree set

Status:

• v1-now

orca worktree set --worktree branch:feature/foo --display-name "Parser" --issue 123 --comment "parser work" --json
orca worktree set --worktree active --comment "parser work" --json

orca worktree rm

Status:

• v1-now

orca worktree rm --worktree path:/abs/wt --force --json

orca terminal list

Purpose:

• discover live terminal handles for a worktree

Status:

• v1-runtime-layer

Rationale:

• requires shared orchestration service over renderer-owned layout plus main-owned PTYs

orca terminal list --worktree id:repo_1::/repo/.worktrees/feature-foo --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "runtimeId": "runtime_abc123",
    "requestId": "req_123"
  },
  "terminals": [
    {
      "handle": "term_a2",
      "title": "claude",
      "status": "running",
      "worktree": "branch:feature/foo",
      "tabId": "tab_1",
      "tabTitle": "Claude Code",
      "leafId": "leaf_2",
      "preview": "I updated the parser. Do you want me to run the full suite?"
    }
  ]
}

Optional:

• --layout may include secondary tab/layout context when the caller needs it

orca terminal show

Metadata-only.

Status:

• v1-runtime-layer

orca terminal show --terminal term_a2 --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "runtimeId": "runtime_abc123",
    "requestId": "req_123"
  },
  "terminal": {
    "handle": "term_a2",
    "title": "claude",
    "status": "running",
    "cwd": "/abs/wt",
    "tabId": "tab_1",
    "tabTitle": "Claude Code",
    "leafId": "leaf_2",
    "lastOutputAt": 1712345678,
    "lastInputAt": 1712345600,
    "preview": "I updated the parser. Do you want me to run the full suite?"
  }
}

orca terminal read

Content-only, bounded.

Status:

• v1-runtime-layer

orca terminal read --terminal term_a2 --json

Response:

{
  "_meta": {
    "orcaVersion": "1.0.0",
    "runtimeId": "runtime_abc123",
    "requestId": "req_123",
    "truncated": false
  },
  "terminal": {
    "handle": "term_a2",
    "status": "running",
    "tail": [
      "Running targeted tests...",
      "3 passed",
      "I updated the parser and fixed the failing snapshot."
    ],
    "nextCursor": null
  }
}

orca terminal send

Status:

• v1-runtime-layer

Supported forms:

• --text <text>
• --enter
• --interrupt

orca terminal send --terminal term_a2 --text "continue" --json

orca terminal wait

Status:

• exit: v1-runtime-layer
• input: deferred
• idle: deferred
• output: deferred

Rationale:

• exit can be grounded in PTY exit events
• the others require new runtime instrumentation and/or heuristics

orca terminal wait --terminal term_a2 --for exit --json

For unsupported wait modes in initial v1:

{
  "_meta": {
    "requestId": "req_123"
  },
  "error": {
    "code": "not_supported_in_v1",
    "message": "terminal wait --for input requires runtime instrumentation that is not available in v1.",
    "retryable": false
  }
}

orca terminal stop

Stop live terminals for a worktree.

Status:

• v1-runtime-layer

This replaces worktree shutdown in the primary surface because the action is terminal-oriented.

Initial supported target:

• --worktree <selector>

Later extension:

• --terminal <handle>

orca file ls

Status:

• v1-now

orca file ls --worktree id:repo_1::/repo/.worktrees/feature-foo --path src --json

orca file read

Status:

• v1-now

orca file read --worktree id:repo_1::/repo/.worktrees/feature-foo --path src/main.ts --json

orca file write

Status:

• v1-now

orca file write --worktree id:repo_1::/repo/.worktrees/feature-foo --path src/main.ts --stdin --json

orca file create

Status:

• v1-now

orca file mkdir

Status:

• v1-now

orca file rename

Status:

• v1-now

orca file rm

Status:

• v1-now

orca file stat

Status:

• v1-now

orca search text

Status:

• v1-now

orca search text --worktree id:repo_1::/repo/.worktrees/feature-foo --query worktree --json

orca search files

Status:

• v1-now

Keep separate from file ls --query in v1.

Rationale:

• clearer distinction between tree listing and search behavior
• aligns with existing product/search mental model

orca git status

Status:

• v1-now

orca git diff

Status:

• v1-now

orca git stage

Status:

• v1-now

orca git unstage

Status:

• v1-now

orca git discard

Status:

• v1-now

orca git branch-compare

Status:

• v1-now

orca gh pr

Status:

• v1-now

orca gh issue

Status:

• v1-now

orca gh issues

Status:

• v1-now

orca gh checks

Status:

• v1-now

Explicitly Deferred From V1

Deferred:

• tab creation and closure
• pane split and close
• tab reordering
• tab colors
• unread/read metadata commands in the core surface
• terminal wait modes other than exit

Rationale:

• either too UI-shaped
• or not grounded in current backend ownership

Recommended Implementation Order

1. repo/worktree/file/search/git/gh v1-now commands
2. shared runtime/orchestration layer with runtimeId
3. status
4. terminal handle issuance and validation
5. terminal list/show/read/send
6. worktree ps
7. terminal wait --for exit

Recommendation

This spec is the contract to review next.

It is intentionally strict and narrower than the broader design docs:

• selectors are formal
• handles are ephemeral by default
• JSON is contractual
• terminal features are split between v1-now and v1-runtime-layer

That should let us optimize for both agent clarity and implementation honesty.