KODEO Local

Your terminal.Your editor.Same room.

Pull a KODEO project into a real folder, edit it with anything, and keep it in sync while your teammates keep working in the browser. Or use plain git. Every change goes through the same rules as the editor.

npm i -g @kodeohq/cli
Start freeEvery command

Four ways in

One project,wherever you type.

KODEO for VS Code

Live in your editor

VS Code, Cursor, Windsurf or vscode.dev in the room: teammates’ cursors, comments, chat, follow mode and the project’s Git — straight from KODEO or in a linked folder.

Extensions → search “KODEO” (publisher kodeohq)
KODEO: Sign In
KODEO: Open Project…

The kodeo CLI

A folder that syncs itself

Clone into a real folder, edit in JetBrains, Neovim, Zed or anything else, then push — or leave kodeo watch running and forget it exists.

npm i -g @kodeohq/cli
kodeo login
kodeo clone acme/storefront
kodeo watch

KODEO as a Git remote

Plain git, no plugin

git clone, fetch and push against git.kodeo.website. Pushing to the project’s branch moves the files everyone sees; other branches just move.

git clone https://git.kodeo.website/acme/storefront
git push

CI and scripts

Tokens that can’t be misread

Scoped, expiring personal access tokens. No prompts under CI=true, versioned --json output, documented exit codes.

export KODEO_TOKEN=kdo_p_…
npx @kodeohq/cli clone acme/storefront --json

Safe by default

It never guesseswith your work.

The server decides; the CLI explains. Every refusal comes back with a reason, the next step, and an exit code a script can rely on.

--dry-run on every write

See exactly what would move, in both directions, before it does.

Real three-way merges

Changed on both sides? Merged with diff3. Real conflicts get markers — never a silent overwrite.

All or nothing

A push is one transaction. If any file moved on KODEO since your pull, nothing lands — and you’re told who changed what.

Ignore rules

.kodeoignore and .gitignore. node_modules, .git and OS junk never move, whatever the files say.

Secrets ask first

.env files, keys and anything that looks like a credential ask before their first push — and are refused in CI.

Binary by the bytes

Decided by content, not extension. Binary files never get conflict markers: KODEO’s copy is saved beside yours.

Limits before transfer

Plan limits are checked on the file list, before a byte is uploaded — with a link to buy storage when that’s the fix.

Deletes go to the trash

Grouped as one restorable push, for 7 days — kodeo trash restore brings them back.

Signing in

A token isa session.

How KODEO protects you

Reference

Every command,every flag.

Open any command for what it does, its options and examples you can copy. The same help is in your terminal: kodeo help push.

23 commands

Sign in & your account

Sign a computer in, see what it may do, sign it out — and manage the tokens CI uses.

kodeo loginSign this computer in to KODEO.
kodeo login [--device] [--read-only] [--no-git] [--no-browser]

Opens KODEO in your browser; you choose what the CLI may do (read or write, Git, all or some workspaces) and approve. The sign-in is kept in your OS keychain and bound to this computer — a copy of it doesn’t work anywhere else. It also offers to set git up for git.kodeo.website.

--device
Print a code to enter at kodeo.website/device instead — for SSH, containers and machines without a browser.
--read-only
Ask for read-only access (clone, pull, status; no push).
--no-git
Don’t set git up for git.kodeo.website.
--no-browser
Print the sign-in link instead of opening a browser.
kodeo login
kodeo login --deviceon a server over SSH
kodeo logoutSign this computer out — on KODEO too.
kodeo logout

Ends the session on KODEO (it disappears from Settings → Local access) and deletes it from this computer.

kodeo logout
kodeo whoamiWho you’re signed in as, and what this sign-in can do.
kodeo whoami

Shows the account, the computer, its access (read or write, which workspaces, Git) and when it expires.

kodeo whoami
kodeo whoami --jsonfor scripts
kodeo tokensPersonal access tokens for CI and scripts.
kodeo tokens [list | create | revoke <id>]

Lists your tokens (name, prefix, access, expiry, last use). create opens Settings → Local access, because tokens are made in the browser behind “Confirm it’s you” — a token can never make more tokens. revoke takes the id or the token’s prefix and stops it at once.

kodeo tokens
kodeo tokens create
kodeo tokens revoke 3f9a1c2e

Projects & folders

Get a project into a folder, start one from a folder, or attach an existing folder.

kodeo projectsThe projects this sign-in can reach, by workspace.
kodeo projects [--names]

Each with your role, branch, file count, size and last change.

--names
Print only workspace/project, one per line (for scripts).
kodeo projects
kodeo projects --names
kodeo cloneDownload a project into a new linked folder.
kodeo clone <workspace>/<project> [folder]

Byte-identical, binary files and empty folders included. Writes a starter .kodeoignore for your framework (build output and caches stay on your machine). Refuses a folder that isn’t empty.

kodeo clone acme/storefront
kodeo clone acme/storefront shopinto ./shop
kodeo initTurn this folder into a new KODEO project and upload it.
kodeo init [--workspace <slug>] [--name <name>] [--yes]

Asks which workspace (or takes --workspace), creates the project and pushes the folder — ignore rules, secret checks and plan limits apply.

--workspace <slug>
The workspace to create it in.
--name <name>
The project’s name (default: the folder’s name).
--allow-secrets <path>
Upload a file that looks like a secret (repeatable).
kodeo init
kodeo init --workspace acme --name "Landing page" --yes

Syncing

See what changed, bring KODEO’s changes down, send yours up — or keep both in step automatically.

kodeo statusWhat changed here, on KODEO, or both.
kodeo status [--offline]

Lists your changes (A added, M modified, D deleted, renames), KODEO’s changes and files changed on both sides. Only files whose size or time changed are hashed, so it’s fast on big folders.

--offline
Only look at this folder (no network).
kodeo status
kodeo status --json
kodeo diffUnified diffs between this folder and KODEO.
kodeo diff [path]
kodeo diff
kodeo diff src/app.ts
kodeo pullGet KODEO’s changes, merged with yours.
kodeo pull [--ours | --theirs] [--diff3] [--switch] [--dry-run]

A file changed on both sides is merged three-way; if the same lines changed, conflict markers (<<<<<<<) are written and the file isn’t pushed until you fix it. Binary files never get markers: yours stays and KODEO’s is saved beside it as name.kodeo.ext. An interrupted pull is finished next time, never left half-applied.

--ours
Resolve every conflict with your version.
--theirs
Resolve every conflict with KODEO’s version.
--diff3
Conflict markers include the common base.
--switch
Follow the project to the branch it switched to.
--dry-run
Show what would change, change nothing.
kodeo pull
kodeo pull --theirs
kodeo pull --dry-run
kodeo pushSend your changes as one all-or-nothing transaction.
kodeo push [--dry-run] [--allow-secrets <path>] [--force]

Refused as a whole if any file you’re pushing changed on KODEO since your last pull — you’re told who changed it; run kodeo pull, then push. Plan limits are checked before anything uploads, only new content travels, files open in a teammate’s editor are merged into it live, and deletes go to the 7-day trash. Files that look like secrets (.env, keys) ask first, and are refused under CI unless named with --allow-secrets.

--dry-run
Show exactly what would be pushed, push nothing.
--allow-secrets <path>
Push a file that looks like a secret (repeatable; required under CI).
--force
Push files that still contain conflict markers, as they are.
kodeo push --dry-run
kodeo push
kodeo watchKeep this folder and KODEO in sync while you work.
kodeo watch [--diff3] [--poll <seconds>]

Pushes each save once the file stops changing, and pulls teammates’ edits within about a second. Teammates see you as “syncing from a local folder”. A conflict pauses only that file. Ctrl+C stops it; it also stops, and says why, if the sign-in is ended.

--diff3
Conflict markers include the common base.
--poll <seconds>
How often to double-check KODEO as a backup to the live connection (default 15).
kodeo watch

The browser, history & trash

Jump to the editor, save and restore checkpoints, and bring deleted files back.

kodeo openOpen the project in the browser — or in VS Code — at a file and line if you give one.
kodeo open [file[:line]] [--vscode | --insiders | --cursor | --windsurf | --vscodium]

With --vscode (or another editor’s flag) the project opens in that editor through KODEO for VS Code: this folder if it’s linked, otherwise straight from KODEO. The extension must be installed there.

--vscode
Open in VS Code (KODEO for VS Code).
--insiders
Open in VS Code Insiders.
--cursor
Open in Cursor.
--windsurf
Open in Windsurf.
--vscodium
Open in VSCodium.
kodeo open
kodeo open src/app.ts:42
kodeo open src/app.ts:42 --vscodethe same line in VS Code
kodeo checkpointSave a named checkpoint of a file on KODEO, or list them.
kodeo checkpoint <file> [name] · kodeo checkpoint list [file]

The same checkpoints as the editor’s history panel.

kodeo checkpoint src/app.ts "before refactor"
kodeo checkpoint list src/app.ts
kodeo restorePut a checkpoint back on KODEO, then pull it here.
kodeo restore <checkpoint-id>

Takes the id (or its first characters) from kodeo checkpoint list.

kodeo restore 8c1e22
kodeo trashKODEO’s 7-day trash — including files a push deleted.
kodeo trash · kodeo trash restore <id>

A push’s deletes are grouped, so one restore brings them all back.

kodeo trash
kodeo trash restore 51d0aa

Git, diagnostics & your shell

Let git sign in through kodeo, find out what’s wrong, and get tab completion.

kodeo git-credentialGit’s credential helper for git.kodeo.website.
kodeo git-credential

kodeo login sets it up for you (for KODEO’s Git host only). Git then gets a one-hour, Git-only credential for each clone or push — nothing long-lived is stored in ~/.git-credentials. You never run it yourself.

git config --global --add credential.https://git.kodeo.website.helper ""what login does, step 1
git config --global --add credential.https://git.kodeo.website.helper "!kodeo git-credential"step 2
kodeo doctorCheck everything, with the fix for anything wrong.
kodeo doctor

Node.js, proxy, connection and TLS, your clock, the version, the keychain, the sign-in and session, git and the git helper, KODEO for VS Code, and where the CLI keeps its settings.

kodeo doctor
kodeo doctor --json
kodeo authHand your sign-in to KODEO for VS Code — as a new sign-in, nothing copied.
kodeo auth handoff --challenge=<S256> --key=<ed25519>

Used by the extension’s “Use My kodeo CLI Sign-In”: the extension makes its own key and PKCE secret and passes only their public halves; this asks KODEO for a one-minute, single-use code that only the extension can trade — for a new VS Code sign-in (its own row in Settings → Local access, never wider than this one). You don’t normally run it yourself.

--challenge
The extension’s PKCE challenge (base64url SHA-256 of its secret).
--key
The extension’s own public device key.
kodeo auth handoff --challenge=… --key=… --jsonwhat the extension runs
kodeo completionTab completion for your shell.
kodeo completion <bash | zsh | fish | powershell>
kodeo completion powershell >> $PROFILEPowerShell
kodeo completion bash >> ~/.bashrcbash
kodeo completion zsh > "${fpath[1]}/_kodeo"zsh
kodeo completion fish > ~/.config/fish/completions/kodeo.fishfish
kodeo helpHelp for every command, one command, or the exit codes.
kodeo help [command] · kodeo help exit-codes
kodeo help
kodeo help push
kodeo help exit-codes

Every command also takes

--json
Machine-readable output with a versioned schema (kodeo.<command>/1).
--quiet
Only errors.
--verbose
Show every request KODEO answers — method, path, status, size and time (on stderr, never a token).
--no-color
Plain text (also NO_COLOR=1).
--yes
Answer yes to questions (they’re never asked under CI=true).
--server <url>
Another KODEO server (also KODEO_URL).
--version
Print the version.
--help
Help for the command.

Environment

KODEO_TOKEN
A personal access token (kdo_p_…). Used instead of kodeo login; no prompts, no keychain. Remove it from your shell to use your sign-in again.
CI=true
Never prompt — a flag is needed instead (e.g. --yes, --allow-secrets).
KODEO_URL
Another KODEO server (default https://www.kodeo.website).
HTTPS_PROXY / NO_PROXY
Go through a proxy, or skip it for some hosts.
NODE_EXTRA_CA_CERTS / KODEO_CA_FILE
Trust a company certificate (TLS inspection).
NO_COLOR
Plain text.
KODEO_NO_UPDATE_CHECK
Don’t mention newer versions.
KODEO_CONFIG_DIR
Where settings and sign-ins are kept (default: your user config folder).

KODEO as a Git remote

Plain git, no plugin: after kodeo login has set git up, these just work — git asks kodeo for a one-hour credential behind the scenes.

git clone https://git.kodeo.website/acme/storefronta full clone
git clone --depth 1 https://git.kodeo.website/acme/storefrontonly the latest commit (fast)
git clone --filter=blob:none https://git.kodeo.website/acme/storefronthistory now, file contents when needed
git pushto the project’s branch: the project’s files change for everyone
git push -u origin my-branchanother branch: it just moves
git fetch --unshallowturn a shallow clone into a full one
git clone https://kodeo:$KODEO_TOKEN@git.kodeo.website/acme/storefrontin CI, with a token that has Git access

A push is refused, with the reason, when:

  • A teammate has unsaved or uncommitted changes to a file the push changes (you’re told who).
  • Rewriting the project’s branch (no force-push to the branch everyone is on).
  • A secret in the new commits, a branch policy, a Viewer’s role, maintenance, or the plan’s repository size.

Exit codes · the same in every command · kodeo help exit-codes

0 Success1 Something went wrong (see the message)2 The command was used incorrectly3 Not signed in, or the token was rejected4 Conflicts were written into files5 Push refused: files changed on KODEO since your last pull6 A plan limit was reached7 KODEO could not be reached8 Not found, or you have no access9 Blocked by a workspace policy

Start to finish

First time

  1. npm i -g @kodeohq/cli
  2. kodeo login
  3. kodeo projects
  4. kodeo clone acme/storefront
  5. cd storefront

A day’s work

  1. kodeo pull

    start from the latest

  2. kodeo status
  3. kodeo diff
  4. kodeo push

Hands-free

  1. kodeo watch

    leave it running; Ctrl+C to stop

Resolving a conflict

  1. kodeo pull

    writes <<<<<<< markers where both sides changed the same lines

  2. kodeo status

    lists the conflicted files

  3. kodeo push

    after you edit the markers out

A server with no browser (SSH)

  1. npm i -g @kodeohq/cli
  2. kodeo login --device

    approve the code on your phone at kodeo.website/device

  3. kodeo clone acme/storefront

CI (GitHub Actions and others)

  1. export KODEO_TOKEN=kdo_p_…

    from Settings → Local access, kept in your CI’s secrets

  2. npx @kodeohq/cli clone acme/storefront --json
  3. cd storefront && npx @kodeohq/cli push --json

Plain git

  1. kodeo login

    once — sets git up

  2. git clone https://git.kodeo.website/acme/storefront
  3. git commit -am "…" && git push

From the CLI to VS Code

  1. kodeo open src/app.ts:42 --vscode

    the same line in VS Code (KODEO for VS Code installed)

KODEO for VS Code — all 57 commands

In the Command Palette (Ctrl+Shift+P / ⌘⇧P) under KODEO: and KODEO Git:. Install it from the Visual Studio Marketplace or, for Cursor, Windsurf and VSCodium, Open VSX.

Sign in

  • KODEO: Sign InApprove in your browser (passkey or two-factor as usual). The code comes back through the extension’s own link and works once.
  • KODEO: Sign In with a CodeFor machines without a browser: approve a short code at kodeo.website/device.
  • KODEO: Use My kodeo CLI Sign-InA new VS Code sign-in from your signed-in kodeo CLI — nothing is copied. Desktop only.
  • KODEO: Sign OutEnds this editor’s sign-in on KODEO too.

Projects

  • KODEO: Open Project…Pick a project (or paste acme/storefront:src/app.ts:42): your linked folder if this computer has one, otherwise straight from KODEO.
  • KODEO: Clone Project into a Folder…Real files that stay in sync — the same folder kodeo clone makes. Desktop only.
  • KODEO: Sync Linked Folder NowPull teammates’ changes and send yours, right now.
  • KODEO: Go to File…Ctrl+P (kodeo://)Every file in the project — also ⌘P / Ctrl+P in a kodeo:// window.
  • KODEO: Search in Project…Ctrl+Shift+F (kodeo://)KODEO’s own project search, results opening at the line — also ⌘⇧F / Ctrl+Shift+F in a kodeo:// window.
  • KODEO: Open in BrowserThis file and line in KODEO’s web editor.
  • KODEO: Copy Link to This LineA link teammates can open in the browser or VS Code.
  • KODEO: Create CheckpointA named checkpoint of this file — the same history as the web editor.
  • KODEO: Checkpoints…List, and restore one (for everyone, undoable).
  • KODEO Trash: Empty TrashThe Trash view (KODEO sidebar) lists deleted files for 7 days — Restore brings one back for everyone; this empties it for good.
  • KODEO: Run in KODEOOpens the project’s Run panel in the browser — the shared runtime teammates can watch.

In the room

  • KODEO: Follow a Teammate…Follow their file, cursor and scrolling. Typing, scrolling or Esc stops.
  • KODEO: Stop FollowingEscStop following.
  • KODEO: Bring Everyone HereSend the room to your line, with a note.
  • KODEO: Comment on This LineAlt+CStart a comment thread on the line — teammates see it in the browser at once.
  • KODEO: Show People and ChatCtrl+Shift+J / ⌘⇧JWho’s here (and in which editor), and the room’s chat.
  • KODEO: Open ChatThe room’s chat as an editor tab — as wide as you like.
  • KODEO: Keyboard ShortcutsAlt+/Every KODEO shortcut in one list — pick one to run it, or change the keys.
  • KODEO: Undo My Last EditCtrl+Z / ⌘ZUndo in a live file — only your own edits, never a teammate’s.
  • KODEO: Redo My Last EditCtrl+Shift+Z / ⌘⇧ZRedo your own edit.
  • KODEO: Ask AssistKODEO Assist right here, beside your code (also in the KODEO sidebar) — answers stream in, with the Help articles they come from. It’s told which editor you’re in and whether you’re live — never your code.
  • KODEO: Show KODEO StatusEverything you can do from here (also the status bar item).
  • KODEO: RefreshReload the project’s files, Git state and notifications.
  • KODEO: Mark All as ReadYour KODEO notifications, all read.

Source Control (the project’s Git)

  • KODEO Git: CommitCommit your staged changes — with co-authors from the room. Live files are settled first, so the commit holds what’s on screen.
  • KODEO Git: Commit & PushCommit, then push to GitHub (on KODEO’s server).
  • KODEO Git: Commit (Amend)Amend the last commit — refused once it’s pushed.
  • KODEO Git: Stage All ChangesYour staging is yours — teammates stage their own.
  • KODEO Git: Unstage All ChangesUnstage everything you staged.
  • KODEO Git: Switch Branch…Switches the project for everyone; your uncommitted changes are parked and come back.
  • KODEO Git: Create Branch…A new branch, optionally switching to it.
  • KODEO Git: PullFrom GitHub, merged on KODEO’s server.
  • KODEO Git: PushTo GitHub — your GitHub token never reaches VS Code.
  • KODEO Git: FetchWhat’s new on GitHub.
  • KODEO Git: Publish to GitHub…Create a GitHub repository for this project.
  • KODEO Git: Initialize RepositoryStart Git for this project (for everyone in it), with an optional .gitignore.
  • KODEO Git: Clone from GitHub…Any public repository by link, or one of yours — its files become the project’s (the old ones go to the trash).
  • KODEO Git: Link a GitHub Repository…Point pushes and pulls at an existing GitHub repository.
  • KODEO Git: Unlink GitHub RepositoryStop syncing with GitHub; the history stays.
  • KODEO Git: Merge Branch…Merge another branch into the current one — conflicts show up in Source Control and in the files.
  • KODEO Git: Abort MergePut the files back as they were before the merge.
  • KODEO Git: Rename Branch…Rename a branch.
  • KODEO Git: Delete Branch…Delete a branch (asks before dropping unmerged work).
  • KODEO Git: Stash Changes…Put your changes aside; Pop / Apply / Drop Stash… bring them back or discard them.
  • KODEO Git: Pop Stash…Apply a stash and drop it.
  • KODEO Git: Apply Stash…Apply a stash and keep it.
  • KODEO Git: Drop Stash…Delete a stash for good.
  • KODEO Git: Create Tag…Tag the current commit (a message makes it annotated). Right-click a commit in KODEO History to tag that one.
  • KODEO Git: Delete Tag…Delete a tag on KODEO.
  • KODEO Git: File HistoryThe commits that changed this file, in KODEO History (Source Control) — each opens as a diff; right-click to restore that version.
  • KODEO Git: RefreshReload the repository state.
  • KODEO Git: Create Pull Request…From the current branch to the default one.
  • KODEO Git: RefreshReload pull requests and CI checks.

Settings

  • kodeo.serverThe KODEO server (https only; http://localhost for development). Default https://www.kodeo.website.
  • kodeo.presence.showNamesShow teammates’ names next to their cursors (initials once they’re still); hover a cursor for who, where and what. Default on.
  • kodeo.roomMessagesPop up teammates’ comments, replies and chat messages. Default on.
  • kodeo.git.inlineBlameWho last changed the line your cursor is on, at the end of the line. Default on.
  • kodeo.linkedFolder.syncOnSaveIn a linked folder, send saved files to KODEO right away. Default on.
  • kodeo.openLinksInWhere Open in VS Code links open a project: linked (default) · remote · ask.

Questions

Asked, andanswered plainly.

Can I run my project locally?
Yes — it’s real files on your disk, so npm run dev, tests and builds work in any terminal. That run is yours: teammates don’t see its output or its preview, and it uses no runtime hours. The code you change still reaches KODEO with every push (or every save, under kodeo watch).
Does the browser editor change?
No. Nothing here is load-bearing: with the CLI missing or the Git remote down, the editor works exactly as before. When you push a file a teammate has open, it’s merged into their editor as a minimal change — their cursor stays put and their unsaved typing survives.
How is signing in protected?
kodeo login uses your browser (PKCE, returning only to 127.0.0.1) or a device code you approve with a passkey, your authenticator or your password — never an email code. Each sign-in is bound to a key in your computer’s keychain and appears in Settings → Local access, where one click ends it.
What happens if two people change the same file?
A push based on an old version is refused as a whole, saying who changed what. kodeo pull merges both sides; if the same lines changed, it writes conflict markers and marks the file until you resolve it. kodeo watch pauses just that file and keeps everything else flowing.
Which systems does it run on?
Anywhere Node 20 runs: Windows, macOS and Linux. Sign-ins are kept in the macOS Keychain, Windows DPAPI or the Secret Service on Linux; on a machine without one it says so and uses a private file only if you agree.
What about VS Code?
KODEO for VS Code (publisher kodeohq) puts VS Code, Cursor, Windsurf, VSCodium and vscode.dev in the room: live editing with teammates’ cursors, comments, chat, follow mode and Source Control. It opens a project straight from KODEO or uses a folder cloned with kodeo — and kodeo open --vscode opens a file there from your terminal.

Ready whenyou are.

A workspace, a project and a live editor in under a minute. Free, no card.

Start building free
Read the Help Center