CLI command reference

Run upstream --help at any time to see the command surface installed on your machine.

Authentication

upstream auth login
upstream auth status [--json]
upstream auth setup-git
upstream auth logout

setup-git installs or repairs the HTTPS credential helper. A successful login runs it automatically.

Workspaces and repositories

upstream push [--name {name}] [--remote {remote}] [--json]
upstream workspace list [--json]
upstream workspace use {namespace}
upstream repo list [--json]
upstream repo create {slug} --workspace {namespace} [--visibility private|public|internal] [--wait] [--timeout 120] [--idempotency-key KEY] [--json]
upstream repo view [{namespace}/{repository}] [--json]
upstream repo clone {namespace}/{repository} [directory] [--ssh] [--open vscode|zed|cursor|windsurf]
upstream repo delete {namespace}/{repository}

upstream push pushes the current folder and creates the repository on first use: a private repository in your default namespace when signed in, an unclaimed repository when signed out. It initializes Git in a folder that has none.

Creation defaults to private. Use the returned slug and clone URL; names can be normalized. The --ssh clone option requires SSH to appear in the repository's Clone menu. On releases supporting --wait, the command waits for the canonical operation. Resume pending work without creating another repository:

upstream operation wait {operation-id} --workspace {namespace} [--timeout 120] [--json]

Keep the printed idempotency key to retry an interrupted create request with the same inputs. Hosted docs may be newer than your installed release; use upstream --help and the release manifest to check available capabilities.

Inside a clone, repository-aware commands discover Upstream remotes, including when GitHub remains origin. Use -R namespace/repository for an explicit Change Request target.

Change Requests

upstream cr list [-R {namespace}/{repository}]
upstream cr create -t "Title" [-H head] [-B base] [--push]
upstream cr view {number}
upstream cr diff {number} [--version N]
upstream cr comment {number} --body "Comment"
upstream cr review {number} --approve
upstream cr checks {number}
upstream cr checkout {number}
upstream cr update {number}
upstream cr ready|close|reopen {number}
upstream cr merge {number} [--squash|--rebase]
upstream cr rebase {number}
upstream cr stack -R {namespace}/{repository}

Reviews and checks remain pinned to the Change Request version they evaluated.

Rules and raw API reads

upstream ruleset list {namespace}/{repository}
upstream ruleset view {namespace}/{repository}
upstream api /api/v1/upstream/...

upstream api currently performs an authenticated GET with your CLI session. It is useful for inspection, not a generic mutation command.

Editors and diagnostics

upstream setup [git|vscode|zed|cursor|windsurf] [--project PATH] [--config PATH] [--read-only] [--dry-run] [--json]
upstream doctor [--json] [--offline]
upstream browse [namespace/repository] [--changes|--new-change] [--print|--json]

See Editors and Git clients for setup locations, task-menu actions, release requirements and client-specific authentication.

Updates

upstream config get-channel
upstream config set-channel stable|latest
upstream update