Documentation
Editors and Git clients
Use Upstream in VS Code, Zed, Cursor, Windsurf, and other Git clients.
Use Upstream in your editor and Git client. Your repositories use standard Git; your agent uses the same account through the CLI and MCP.
Set up your editor
Install the Upstream CLI, open your project in a terminal, and run one command:
| Editor | Command |
|---|---|
| VS Code | upstream setup vscode |
| Zed | upstream setup zed |
| Cursor | upstream setup cursor |
| Windsurf | upstream setup windsurf |
| Other editors and Git clients | upstream setup git |
Setup reuses a valid login or starts browser sign-in. It configures Git authentication, adds Upstream actions to supported editors, and connects their agents through MCP. Your editor still asks you to trust the project and start the server.
These commands require a CLI release that lists setup in upstream --help. Check the release manifest for capabilities.editorSetup. Reinstalling an older release does not add newer commands. Until an editor-capable release is available, use upstream auth login and upstream auth setup-git for Git, then configure MCP using the agent guide if your installed release supports it.
For a repository you have not cloned yet:
upstream auth login
upstream repo clone YOUR_NAMESPACE/YOUR_REPOSITORY --open vscode
Replace vscode with zed, cursor, or windsurf. This clones the repository, configures the editor, and opens the folder. If the editor launcher is unavailable, the CLI prints the cloned folder so you can open it yourself.
Use the editor you know
Stage, commit, branch, fetch and push through the editor's normal Git controls. Use the repository's Upstream clone URL. In VS Code, Git: Clone accepts this URL directly. A GitHub account is not required for Upstream Git access.
Setup adds these actions to Tasks: Run Task in VS Code and compatible editors, or task: spawn in Zed:
- Upstream: Sign in
- Upstream: Check connection
- Upstream: Open repository
- Upstream: Open Change Requests
- Upstream: Propose current branch
- Upstream: List repositories
Push your feature branch, then choose Propose current branch to open a Change Request in the browser. The action opens the form with your branch selected; it does not push, create a request or merge on your behalf. Default-branch protection still applies.
For agent access, start Upstream under MCP: List Servers in VS Code, AI → MCP Servers in Zed, or the editor's MCP settings. The agent can inspect repositories, create Change Requests, review changes and use the other tools exposed by upstream agent tools. Configuring a server does not prove it has connected; check its status in the editor.
Other Git clients
Run upstream setup git, then clone by URL or open an existing local clone. Git clients that use your configured Git credential helper can reuse your Upstream login. The helper uses an absolute executable path so the app does not depend on your terminal's PATH.
| Client | Setup |
|---|---|
| JetBrains IDEs | Enable Use credential helper under Settings → Version Control → Git, then clone the Upstream URL. |
| GitKraken | Use Clone Repo with the repository URL. If HTTPS does not use your helper, add the public part of an account SSH key in Upstream, choose it in GitKraken's SSH settings, and clone with the SSH URL. |
| Tower, Fork and Sourcetree | Add the repository by URL or open a local clone. Use your Git credential helper when supported, or an account SSH key. |
| GitHub Desktop | Open the local clone through Add Local Repository. GitHub-specific publishing and pull-request buttons still target GitHub; use the Upstream CLI or browser for Change Requests. |
| Terminal clients such as lazygit | Open the clone and use ordinary Git operations with the configured helper. |
Copy an SSH URL only when the repository offers SSH. Register the public key in SSH key settings; keep the private key on your machine. A client's own credential store can override Git helpers. Do not paste a CLI session token into its password field.
Upstream Git support does not make GitHub-only APIs or extensions compatible. GitHub's gh, its pull-request extension, and hosted products that only offer GitHub OAuth need a provider integration or an explicit GitHub sync/mirror arrangement. See Import and GitHub Sync if a required service only accepts GitHub. An Upstream Change Request is managed through Upstream's CLI, MCP or web interface.
Diagnose a connection
upstream doctor
upstream doctor --json
Use CLI 0.6.4 or newer; update an older installation with upstream update. The report checks Git, helper configuration, the CLI session and the project's Upstream remote. CLI 0.6.2 and later also check HTTPS Git access by reading remote refs. CLI 0.6.3 and later reuse the CLI session for Git, avoiding per-operation credential creation limits. Each failure gives a next step. It does not print tokens or raw credential-bearing remotes, and it does not push anything. Use --offline to skip network checks. Never paste git credential fill or upstream credential-helper output into an agent conversation; those commands return credentials.
If terminal Git works but the editor fails, check the client's credential-helper setting, the selected Git executable, and whether it runs locally or over SSH. Run setup on the machine where Git and the MCP server execute. A local login does not sign in a remote host.
Existing configuration and agents
Preview the exact files setup would change:
upstream setup vscode --dry-run --json
Setup preserves JSON comments, other servers, existing tasks and editor preferences. Existing Upstream entries with different settings are left alone and reported. Before changing an existing file, it saves a private backup outside the project. Paths to backups appear in the result.
| Target | MCP configuration | Actions |
|---|---|---|
| VS Code | .vscode/mcp.json | .vscode/tasks.json |
| Zed | .zed/settings.json | .zed/tasks.json |
| Cursor | .cursor/mcp.json | .vscode/tasks.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | .vscode/tasks.json |
Use --project PATH for a different project and --config PATH for a custom MCP configuration location. Generated commands contain this machine's absolute executable path; review them before sharing configuration through Git. They contain no account tokens.
--read-only exposes only inspection tools through MCP. It does not reduce your account's Git permissions or disable normal editor Git controls. --json setup does not start an interactive login: if disconnected, it returns a login-required error and the next command.
CLI commands also work when GitHub remains origin and Upstream has another remote name. They detect Upstream remotes without replacing your existing ones. Use -R namespace/repository for Change Requests when you want an explicit target. To open a repository without launching a browser, use upstream browse --print.