Installing and signing in
cawdev is the whole interface from a machine — one binary, plain Node, zero
dependencies. It is both the terminal you watch sessions in and the daemon that
runs them; typing cawdev finds a daemon on this machine or starts one.
npm install -g cawdev-clicawdevThe package is cawdev-cli on npm;
it needs Node 20 or later and installs one command, cawdev. Working from a
checkout instead? npm install -g ./tools from the repository root installs
the same thing.
The first time, on a machine with nothing set up
Section titled “The first time, on a machine with nothing set up”Nothing is created until every question is answered — a setup abandoned
halfway leaves no token on the tokens page and no config pointing at half a
machine. That is what makes running cawdev again the whole recovery
procedure.
-
Sign in through the browser. No password reaches this process — the CLI asks the platform for a code, opens the sign-in page, and waits for you to approve it there. A password belongs on a page a browser has told you the origin of, not in a full-screen terminal app. If you have added a passkey, the sign-in page offers it, and this sign-in uses it too.
-
Choose which projects this machine should serve. Only ones where you may run agents are offered.
runner:operateneeds the Run agents privilege, so a project you can only see would fail the mint afterwards. The list ends with Create a new project on cawdev: a name, a git URL (or an existing checkout, whoseoriginis then used) and a path. It clones first and creates the project only at the final confirmation, so a clone that fails leaves nothing on the platform. -
Say where checkouts should live. One question, not one per project —
~/cawdevunless you say otherwise. It is a picker: the folder beside checkouts this machine already serves, the default, or a path you type withtabcompleting directories the way a shell does. Each row says what is there already (new folder, will clone here, already a checkout of cawdev). -
It clones what isn’t already there, in the foreground, under your own git credentials. The platform never holds a git credential; it only supplies the URL a project was created with.
-
Say which coding agents are on this machine (Claude Code, Antigravity CLI, Codex CLI; see Agents) and confirm each is signed in. This is the one thing
cawdevcannot do for you — a runner whose agent isn’t signed in boots fine and fails every run, which is a worse way to find out than a question. -
It mints its own
runner:operatetoken, scoped to exactly the projects you chose, and writes the config. Nothing is typed or pasted. The token is checked against your access at every call, so it stops working if you lose the Run agents privilege on a project.
Run cawdev --setup any time to do this again — adding a project to a machine
that already has one is the ordinary reason. For one small change, cawdev config add-project does only that. See The config file. A daemon already running keeps
the config it booted with, so it’s told to restart rather than left looking
like it took the change.
On a machine that already has a config but no token
Section titled “On a machine that already has a config but no token”If a runner.config.json exists — checked in, copied from another machine —
but holds no token, cawdev skips straight to signing in and minting one for
the projects the config already names. Nothing else is asked, because the
config already answers it.
What ends up on disk
Section titled “What ends up on disk”Three files under ~/.cawdev/, each 0600, each answering a different
question:
| File | What it holds | Why it’s separate |
|---|---|---|
session.json |
Your browser session — the cookies from signing in | This is you. No password, and the daemon’s own token is never in here. |
token.json |
This machine’s runner:operate token, keyed by URL |
This is what the machine may do. Revoking it in the console stops the machine without touching your session. |
runner.config.json |
Which projects, which checkouts, which agents | The one file people copy between machines or check in — and the one that must never carry a credential. |
A token can also live in the config — that’s the shape --setup wrote
before this three-file split existed, and it’s still read first if present.
It’s not how a fresh setup writes one, because a config is the kind of file
people keep beside their code and commit.
cawdev the runner here, starting one if there is nonecawdev --runner <name> when this machine runs more than onecawdev --url <url> which cawdev to sign in to (or CAWDEV_URL)cawdev --config <path> the runner config to start a daemon fromcawdev --no-start attach only; never launch a daemoncawdev --watch-only do not sign in; watch without being able to actcawdev --leave-running leave the daemon running when you quitcawdev --setup walk the first-machine questions againcawdev --version this CLI's version, and the platform's--no-start attaches to a daemon that is already there and refuses to launch
one. --watch-only never opens a browser: everything on the socket is readable
without signing in, and watching is the larger half of what the terminal is for.
Anything that changes something (answering, cancelling, deciding a permission)
goes to the platform as you, so it needs a sign-in.
Checking what’s running
Section titled “Checking what’s running”cawdev --version # this CLI's version, and the platform's, needing no sign-incawdev config show # this machine's config, token redactedcawdev warns on startup if this CLI and the platform it’s talking to have
drifted apart, and refuses to start the daemon if this CLI is below the
platform’s stated minimum.