@todesktop/v2

The todesktop command for ToDesktop v2. Set an app up from its repository, follow its builds, and upload from CI, at a terminal or from a coding agent such as Claude Code or Codex.

npx @todesktop/v2 login
npx @todesktop/v2 integrate

Or install it with npm install --global @todesktop/v2. It needs Node.js 24 or later. It installs a todesktop command, like ToDesktop's first CLI (@todesktop/cli), so install one of them globally, not both.

Set an app up

In your app's repository:

todesktop login                 # approve a code in the dashboard
todesktop integrate --app APP_ID

integrate reads your repository: its framework, names, entry point and GitHub remote, and any updater to take out. It then gives the five setup steps your app's Overview shows, filled in for this repository:

1. Add todesktop.config.ts.
2. Add ToDesktop updates.
3. Trust your release workflow (a person does this in the dashboard, from the link integrate and status give; status --wait-for trust waits for it).
4. Build and upload in GitHub Actions.
5. Push a tag.

--write adds the files those steps add and never overwrites one. --step gives one step, and todesktop config check loads your config and checks the apps built on this machine.

Follow builds

todesktop status
todesktop builds list
todesktop builds wait latest --until smoke
todesktop builds logs BUILD_ID

builds wait latest waits for the first upload too, so it can run right after you push the first tag. If ToDesktop refuses the upload because the repository or tag isn't trusted, it says so straight away, with the link to trust it. todesktop commands lists every command.

For agents

When stdout isn't a terminal, or with --json, every command answers with one JSON object:

• { "ok": true, "data": …, "next": [{ "command": … }] }
• { "ok": false, "needs": { "url": … } } when a person must act, such as approving a sign-in or trusting a workflow
• { "ok": false, "error": { "code", "message", "fix" } }

Exit codes: 0 done, 1 failed, 2 wrong usage, 3 a person must act, 4 a failed build or check, 5 timed out. Progress goes to stderr.

Run through npx, the commands it suggests say npx @todesktop/v2 …, so an agent can run them as they are.

To have a coding agent (Claude Code, Codex, Cursor, …) set your app up, give it this line in your app's repository, with your app ID from the dashboard. Your app's Overview copies it for you ("Set up with your coding agent"):

Fetch and follow the instructions at https://app.todesktop.com/agent-setup.md to set up this app with ToDesktop. My ToDesktop app ID is <APP_ID>.

The instructions say how ToDesktop works, what must be true when setup is done and how to check each part, and the rules (no signing secrets, no pushing until you say so). The agent hands back to you to approve its sign-in and to trust your release workflow with your security key.

Without a browser, use a personal access token from the dashboard's Access tokens page as TODESKTOP_TOKEN. Tokens can only read: releasing and CI trust stay in the dashboard, behind a security key.

Upload from CI

In GitHub Actions, use the ToDesktop/upload-action action, which runs todesktop upload and authenticates with the job's own token.