Editor & files

Every kodeo command

The complete reference for the kodeo CLI — all 22 commands with their options and examples, git, environment variables, exit codes and workflows.

13 min readUpdated 29 Sept 2026

Everything the kodeo command-line tool can do. The same reference, searchable, is at kodeo.website/local; in your terminal, kodeo help <command> shows it for one command.

Install

npm i -g @kodeohq/cli

The package is @kodeohq/cli; the command it installs is kodeo. For a one-off (CI, a server) use npx @kodeohq/cli <command>. Needs Node.js 20 or newer.

All 22 commands at a glance

Sign in & your account

kodeo login — Sign this computer in to KODEO.
kodeo logout — Sign this computer out — on KODEO too.
kodeo whoami — Who you’re signed in as, and what this sign-in can do.
kodeo tokens — Personal access tokens for CI and scripts.

Projects & folders

kodeo projects — The projects this sign-in can reach, by workspace.
kodeo clone — Download a project into a new linked folder.
kodeo init — Turn this folder into a new KODEO project and upload it.
kodeo link — Attach this folder to an existing project.
kodeo unlink — Detach this folder.

Syncing

kodeo status — What changed here, on KODEO, or both.
kodeo diff — Unified diffs between this folder and KODEO.
kodeo pull — Get KODEO’s changes, merged with yours.
kodeo push — Send your changes as one all-or-nothing transaction.
kodeo watch — Keep this folder and KODEO in sync while you work.

The browser, history & trash

kodeo open — Open the project in the browser — at a file and line if you give one.
kodeo checkpoint — Save a named checkpoint of a file on KODEO, or list them.
kodeo restore — Put a checkpoint back on KODEO, then pull it here.
kodeo trash — KODEO’s 7-day trash — including files a push deleted.

Git, diagnostics & your shell

kodeo git-credential — Git’s credential helper for git.kodeo.website.
kodeo doctor — Check everything, with the fix for anything wrong.
kodeo completion — Tab completion for your shell.
kodeo help — Help for every command, one command, or the exit codes.

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

Sign 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.

Option	What it does
`--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 --device   # on a server over SSH

kodeo logout

Sign 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 whoami

Who 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 --json   # for scripts

kodeo tokens

Personal 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 projects

The projects this sign-in can reach, by workspace.

kodeo projects [--names]

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

Option	What it does
`--names`	Print only workspace/project, one per line (for scripts).

kodeo projects
kodeo projects --names

kodeo clone

Download 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 shop   # into ./shop

kodeo init

Turn 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.

Option	What it does
`--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

kodeo link

Attach this folder to an existing project.

kodeo link <workspace>/<project> [--diff3]

Nothing is overwritten: files on both sides that differ are merged, or marked as conflicts. Then kodeo status shows what differs and kodeo push sends your side.

Option	What it does
`--diff3`	Conflict markers include the common base.

kodeo link acme/storefront

kodeo unlink

Detach this folder.

kodeo unlink

Removes .kodeo/local. Your files and the project on KODEO are untouched.

kodeo unlink

Syncing

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

kodeo status

What 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.

Option	What it does
`--offline`	Only look at this folder (no network).

kodeo status
kodeo status --json

kodeo diff

Unified diffs between this folder and KODEO.

kodeo diff [path]

kodeo diff
kodeo diff src/app.ts

kodeo pull

Get 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.

Option	What it does
`--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 push

Send 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.

Option	What it does
`--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 watch

Keep 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.

Option	What it does
`--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 open

Open the project in the browser — at a file and line if you give one.

kodeo open [file[:line]]

kodeo open
kodeo open src/app.ts:42

kodeo checkpoint

Save 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 restore

Put 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 trash

KODEO’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-credential

Git’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 doctor

Check 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, and where the CLI keeps its settings.

kodeo doctor
kodeo doctor --json

kodeo completion

Tab completion for your shell.

kodeo completion <bash | zsh | fish | powershell>

kodeo completion powershell >> $PROFILE   # PowerShell
kodeo completion bash >> ~/.bashrc   # bash
kodeo completion zsh > "${fpath[1]}/_kodeo"   # zsh
kodeo completion fish > ~/.config/fish/completions/kodeo.fish   # fish

kodeo help

Help 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

Options every command takes

Option	What it does
`--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.

KODEO as a Git remote

Plain git, no plugin. After kodeo login has set git up, git asks kodeo for a one-hour, Git-only credential behind the scenes — nothing long-lived is stored.

git clone https://git.kodeo.website/acme/storefront   # a full clone
git clone --depth 1 https://git.kodeo.website/acme/storefront   # only the latest commit (fast)
git clone --filter=blob:none https://git.kodeo.website/acme/storefront   # history now, file contents when needed
git push   # to the project’s branch: the project’s files change for everyone
git push -u origin my-branch   # another branch: it just moves
git fetch --unshallow   # turn a shallow clone into a full one
git clone https://kodeo:$KODEO_TOKEN@git.kodeo.website/acme/storefront   # in 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.

Environment variables

Variable	What it does
`KODEO_TOKEN`	A personal access token (kdop…). 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 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).

Exit codes

The same in every command, so scripts can rely on them (kodeo help exit-codes).

Code	Meaning
0	Success
1	Something went wrong (see the message)
2	The command was used incorrectly
3	Not signed in, or the token was rejected
4	Conflicts were written into files
5	Push refused: files changed on KODEO since your last pull
6	A plan limit was reached
7	KODEO could not be reached
8	Not found, or you have no access
9	Blocked by a workspace policy

Start to finish

First time

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

A day’s work

kodeo pull   # start from the latest
kodeo status
kodeo diff
kodeo push

Hands-free

kodeo watch   # leave it running; Ctrl+C to stop

Resolving a conflict

kodeo pull   # writes <<<<<<< markers where both sides changed the same lines
kodeo status   # lists the conflicted files
kodeo push   # after you edit the markers out

A server with no browser (SSH)

npm i -g @kodeohq/cli
kodeo login --device   # approve the code on your phone at kodeo.website/device
kodeo clone acme/storefront

CI (GitHub Actions and others)

export KODEO_TOKEN=kdo_p_…   # from Settings → Local access, kept in your CI’s secrets
npx @kodeohq/cli clone acme/storefront --json
cd storefront && npx @kodeohq/cli push --json

Plain git

kodeo login   # once — sets git up
git clone https://git.kodeo.website/acme/storefront
git commit -am "…" && git push

Still have a question about this?

Assist answers from this article — in any language.

Was this helpful?

More in Editor & files

The editorTabs, quick open, project search, autosave, snippets and Emmet, keyboard shortcuts, and the touch editor on phones.Files, uploads and the trashCreate, move and upload files, drag and drop, file limits by plan, and restoring deleted files from the trash.Work locally with the kodeo CLIClone a KODEO project into a folder on your computer, edit it in any editor, and pull and push — or keep it in sync with kodeo watch.KODEO for VS CodeEdit KODEO projects live from VS Code, Cursor, Windsurf, VSCodium or vscode.dev — with your teammates' cursors, comments, chat, follow mode and the project's Git.

All articles Open a ticket