CoDev CLI

The CoDev CLI connects your terminal to your CoDev account. Use it to sign in once, then connect Codex, Claude, or Cursor from the machine where you already use them.

#Set up everything at once

The easiest way is to let your coding agent do it: copy the setup prompt from CoDev's home page (or Get started in CoDev) and paste it into Claude Code, Codex or Cursor. Your agent runs everything below for you and asks you whenever a choice is yours; see the Quickstart. To run setup yourself:

curl -fsSL https://www.trycodev.com/install.sh | sh

On Windows, run it in PowerShell instead:

irm https://www.trycodev.com/install.ps1 | iex

This installs the CLI and runs codev setup, which:

• opens CoDev in your browser so you can sign in or sign up, then connects the CLI to it;
• asks before connecting each of Claude Code, Codex, Cursor and VS Code it finds, and before showing their chats live in the CoDev workspaces they use (off until you say yes). Only the agents you say yes to get the steps below;
• installs CoDev in Claude Code as a plugin named codev (see it, turn it off or remove it in /plugin), which carries CoDev's connector, conflict warnings and the live chat in workspaces, and removes what earlier setups put in Claude Code's own settings;
• tells Claude Code's auto mode that CoDev is your own service, with one line in autoMode.environment in ~/.claude/settings.json (see or remove it in /permissions → Auto mode), so auto mode doesn't block your agent's codev share as data leaving your machine;
• installs codev in Codex as one plugin carrying the signed-in connector, conflict warnings, session briefing and live chat mirror; manage it in /plugins (requires Codex 0.154 or later); open /hooks to review and trust its hooks before they can run, and review changed hooks again after an update;
• turns on conflict warnings for Cursor (see Coordinate your local agent);
• installs CoDev's extension in VS Code and Cursor with their code and cursor commands. You then sign in from its CoDev panel to give the editor's agent CoDev's tools (see Use CoDev from VS Code or Cursor);
• run in a checkout whose workspace has live main, asks once whether to show your work in progress there (see Show your work in live main);
• opens CoDev's Get started guide, and tells you how to put your project on CoDev and invite your team. If GitHub isn't connected to your CoDev account, it gives you the Connect GitHub page's link (and opens that page instead of the guide when it opens one), so the projects you share link to their repositories.

Setup updates each plugin when its content changes and removes only the old CoDev connector and hooks, keeping other settings. It's safe to run again. It never mixes two CoDev servers: if this computer is signed in to a different one, setup stops without changing anything, and an agent whose codev connector points elsewhere is left alone. Add --no-browser to print the links instead of opening them. The setup prompt has your coding agent run it outside its sandbox. Your agent asks you which agents to connect and whether to show their chats, then passes your answers to setup as --agents claude,codex,cursor,vscode (or none) and --mirror on or off; run without them and without a terminal to answer in, setup only refreshes the agents already connected. Start a new Claude Code or Codex session afterwards: the connector loads only in new sessions.

#See and disconnect what's connected

Settings → Security in CoDev lists each computer where you ran codev setup, the agents it connected and whether their chats show in CoDev. Disconnect signs one agent out of CoDev from anywhere; Revoke signs the whole computer out.

codev disconnect claude

Takes CoDev out of that agent on this computer (its plugin, hooks and auto mode line) and signs it out of CoDev. Name codex, cursor or vscode instead, or no agent to disconnect all of them and turn the chat mirror off. For Cursor and VS Code, it also uninstalls CoDev's extension. The extension's own sign-in stays in Settings → Security until you revoke it. codev setup connects them again.

#Check your setup and update

codev status

Shows, one line each, whether this computer is signed in to CoDev, whether this CLI is the newest, whether Claude Code and Codex have CoDev's plugin (and have loaded it in a session, which in Codex also means you trusted its hooks), whether the chat mirror is on, and whether this folder is linked to a workspace. Anything missing comes with the command that fixes it. Your coding agent can run codev status, and those commands, for you: ask it to fix your CoDev setup.

codev update

Installs the newest CLI with npm and runs its codev setup, so CoDev's plugins in Claude Code and Codex use it. The CLI checks npm for a new version in the background at most every six hours. When one is out, codev setup, share, clone, link and login say so before they run, and your coding agent's next session starts by offering to update it for you. Start a new session afterwards so your agent loads the update. In Codex, review CoDev's hooks again in /hooks if they changed.

#Install

The CLI needs Node.js 20 or newer.

npm install -g @trycodev/cli

This installs the codev command. Run codev help to see every command.

#Sign in

codev login

The CLI prints a link and a one-time code (like ABCD-EFGH) and opens your browser. On the Authorize CoDev CLI page, check the code and choose Authorize CLI. The terminal then prints CoDev CLI is connected.

• The code expires after 10 minutes.
• Use codev login --no-browser on a remote machine or over SSH, and open the link yourself.
• The login lasts 90 days. You can see and revoke it under Settings → Security → CLI and app logins. Changing your password revokes every CLI login.

#Connect your AI providers

This is how you connect a Claude, ChatGPT, or Cursor subscription to CoDev. Each command runs the provider's official sign-in on your machine and saves the result to your CoDev account, so your agents can use it in every workspace. Sign in with codev login first.

#Codex

codev codex-auth

Runs codex login with a device code. Add --browser to sign in through your browser instead.

#Claude

codev claude-auth

Runs claude setup-token and saves the token to your account.

#Cursor

codev cursor-auth

Runs Cursor's agent login and saves the result to your account.

If the provider's tool isn't installed, the CLI tells you how to install it:

#Put a project on CoDev

codev share

Run it in your project's folder, or ask your agent to "put this project on CoDev". It creates a workspace named for the folder (--name picks another name), waits for its machine, and uploads the files Git would commit: tracked and untracked, changes you haven't committed included, never ignored files. Outside a Git checkout it takes every file except dependency and build folders such as node_modules, .venv and dist. .env files, keys (.pem, .key, id_rsa) and .npmrc, .pypirc and .netrc stay on your computer; it lists what it left out, so you can add what your project needs as environment variables.

In a checkout of a GitHub repository that already has a workspace with live main you can edit (your team's, or one you shared from another folder), codev share uploads nothing: it names that workspace and tells you to run codev link there, so your work shows in it as your own worktree instead of in a second copy. codev share --new makes a separate workspace anyway.

An upload holds up to 10,000 files and 100 MB, and files over 4 MB are left out. Nothing is sent until the folder fits. When it finishes, it prints the workspace's link and an invite link that adds your teammates as editors.

In a checkout whose origin is a GitHub repository CoDev's GitHub app can open, the workspace is linked to it, so you can push and open pull requests from it. Its main is the newest commit of the default branch your work contains, exactly as GitHub has it, and everything since (your commits and the changes you haven't committed) becomes one commit on a new branch: codev/<your branch>, or codev/local-changes when you were on the default branch. It uploads the whole repository, from its top folder. Before it makes the workspace, it checks that GitHub is connected to your CoDev account and that CoDev's GitHub app can open the repository. When either is missing, it opens the Connect GitHub page (or prints its link with --no-browser), which does both, and waits up to 10 minutes; if you don't finish in time it stops without making a workspace, and you run it again. When it still can't link (the repository has a submodule or a file over 4 MB, or GitHub doesn't have your base commit), it says why and uploads your files without Git history. The first time, it asks you to approve the CLI again in the browser, because CLI logins approved before codev share existed can't create workspaces.

#Show your work in live main

codev link

In a workspace with live main, every member's work, from a laptop, the browser or a cloud agent, shows in the workspace as that member's own worktree, and live main combines it all into one read-only version of the project the team can run. Run codev link in your checkout of the workspace's GitHub repository to show yours: it picks the workspace you used last (or lets you choose one) and asks Show your work in progress to everyone in <workspace>? before anything syncs. Your coding agent can link for you: it asks you in its chat first, then runs codev link --yes --workspace <workspace>. codev setup asks the same once when you run it in a checkout. Only workspaces you can edit are offered.

Once linked:

• While your coding agent works in the checkout, your changes, uncommitted and untracked ones included, sync to your worktree in the workspace, at most every 30 seconds and only when something changed. They travel through your own origin: a hidden ref (refs/codev/wip/...), never a branch, which the workspace fetches. Ignored files never sync, and .env files and keys are left out even when Git doesn't ignore them; a commit that adds one stops the sync until it's gone.
• Each branch you check out gets its own worktree, named codev/<you>/<branch>. Switching back picks up where it was.
• A stopped workspace stays stopped; it catches up the next time it starts. Syncing never keeps a workspace running.
• CoDev never changes files on your computer. When a cloud agent you started finishes, or your work merges, your agent is told the commands to take it (git fetch and git merge, or git pull).

codev link status shows where each branch syncs and when it last did. codev link off stops syncing, deletes the hidden refs and removes your worktree from the workspace (at its next start, if it's stopped); your files stay on your computer. The first time, it may ask you to approve the CLI again in the browser, as codev share does.

#Work on a workspace from your computer

codev clone <workspace>

Joined a teammate's workspace and want to work on your own computer? Pass the workspace's id or link. codev clone clones its GitHub repository into a new folder (or the one you name) with your own Git credentials, then asks the same question as codev link, so your changes show in the workspace as your own worktree. Your coding agent then works in that folder. When the workspace can't take work from your computer (it has no live main or no GitHub repository, or you're a viewer), it says why and you work in the workspace in CoDev instead. Run by your agent, it only clones; your agent then asks you and links the folder on your yes.

#Save to your workspace's Library

codev pages save <workspace> quiz.html

Puts a web page (an HTML file: an app, slides, a quiz, a dashboard) in the workspace's Library, where everyone in the workspace opens it in CoDev without anyone sending a link. The page's <title> names it unless you pass --title. It prints the page's link and the command that updates it: --page <id> replaces that page, so its link always shows the newest version. codev pages list <workspace> shows the workspace's Library with links, and codev pages delete <page> removes one for everyone. Viewers can list pages but not save or delete them.

#Share skills with your team

codev skills save <workspace> ./release-notes

Puts an agent skill in the workspace's Library: a SKILL.md, or a skill folder holding one. Its frontmatter's name (lowercase words joined by hyphens) and description name it, and saving the same name again updates it. codev skills list <workspace> shows the workspace's skills, codev skills show <workspace> <name> prints one, and codev skills delete <workspace> <name> removes one for everyone.

codev skills install <workspace> release-notes

Writes a skill into this computer's Claude Code skills folder (~/.claude/skills/<name>/, or --agent codex for Codex's), after showing what it does and asking you first: a teammate wrote it, and your agent will follow it. An agent running it for you passes --yes once you agreed. Start a new session to load it. Viewers can list, show and install skills but not save or delete them.

#Put a blank workspace on GitHub

codev repo create <workspace>

For a workspace made before you connected GitHub: makes a private repository named after it on your own GitHub account and brings it into the workspace, so its work pushes there, as Create repository in the workspace does. The workspace must be running, and you connect GitHub in CoDev first.

#Cancel a ship

codev ship cancel <workspace>

Stops a live main workspace's ship that is still opening pull requests or waiting for them to merge, so a new one can start, as Cancel ship in the Team panel does. Pull requests it opened stay open on GitHub, to merge or close there. Editors only.

#Coordinate your local agent

codev coordinate setup claude

Prints the hook settings that let your local Codex (or cursor) hear what teammates' agents are changing and when their work conflicts with its own, and the file to merge them into; codev setup gives Claude Code and Codex the hook in their CoDev plugins and adds Cursor's hook to its settings. Your agent hears it after its edits and as each turn starts. While a teammate's agent could test-merge it, your agent's work in progress goes to a hidden ref on your own origin, never a branch. In a linked checkout it also hears what live main says: teammates' work there that touches the same files, and when its own work doesn't fit yet. See Use CoDev from Claude Code or Codex.

#Commands

#Configuration