CLI reference - Docs

Install with npm install -g @deskwink/cli. Options in square brackets are optional; <angle brackets> are values you fill in. This page follows the command list of the version in beta; deskwink help is always the final word for the version you have.

Start, stop and check

deskwink launch [--json] [--no-browser] [--foreground]

The main command. Pairs this computer the first time, asks for a folder if none is set, starts DeskWink in the background, and waits until it is connected. Safe to run again: if DeskWink is already running it only prints the status. --no-browser does not open the pairing link for you. --foreground keeps DeskWink in this terminal (same as deskwink run).

deskwink status [--json] [--wait connected --timeout 600]

Shows the state, account (email partly hidden), computer name, folders, abilities and version. --wait connected blocks until the computer is connected or the timeout in seconds runs out (default 600).

deskwink stop

The local kill switch. DeskWink refuses new work at once, cancels work in progress, disconnects, and exits.

deskwink restart

Stops DeskWink, then launches it again.

deskwink run

Runs DeskWink in this terminal with logs on screen, for debugging. Ctrl+C stops it.

Folders

Folders can only be added, widened or made writable on this computer. The console can remove them or narrow them, never widen them.

deskwink folders list

Lists the folders your AI can reach, and whether each is read-only or allows proposed changes.

deskwink folders add <path> [--write] [--name <n>] [--allow-broad]

Shares a folder. Read-only unless you add --write. --name sets the display name. --allow-broad is needed for your home folder and only works in an interactive terminal; whole drives and system folders cannot be added.

deskwink folders remove <name|path>

Stops sharing a folder.

Abilities and approvals

deskwink capabilities list

Shows which abilities are switched on for this computer.

deskwink capabilities enable shell

Turns on running commands. Only works in an interactive terminal, and asks you to type this computer’s name. It is refused when run from a program DeskWink started. Running commands is planned for the Pro plan.

deskwink capabilities disable <capability>

Turns an ability off. Does not need an interactive terminal. Turning off shell ends all running commands.

deskwink approvals list [--json]

Lists commands your AI has asked to run on this computer and that are waiting for you.

deskwink approvals approve <id>

Shows the full command and folder, then asks you to confirm. Only works in an interactive terminal. The id starts with apr_ or exe_.

deskwink approvals reject <id>

Rejects a waiting command. Does not need an interactive terminal.

Undo and logs

deskwink restore <execution-id> [--force]

Puts back the original of a file DeskWink changed, from the local backup (kept for 7 days). If the file was changed again since, it stops unless you add --force.

deskwink logs [--lines 50] [--follow]

Shows the local log. -f is short for --follow. The log holds metadata only, never file contents or command text.

deskwink doctor [--json] [--report]

Checks your setup and explains what is wrong. --report writes a diagnostic bundle with personal details removed that you can send to support.

Account and computers

deskwink logout

Removes this computer from your DeskWink account, deletes its key from this computer, and stops DeskWink.

deskwink devices

Prints the link to manage your computers in the console. Renaming and removing other computers is done there.

deskwink version

Prints the version. --version and -v do the same.

deskwink help

Prints the command list. --help and -h do the same.

Machine-readable output

launch, status and doctor accept --json and print one JSON document, which coding agents and scripts can read. launch and status use the same shape. state is one of stopped, awaiting_pairing, connecting, connected, suspended, revoked or error.

{
  "schema": "deskwink.status.v1",
  "state": "awaiting_pairing",
  "version": "0.1.0",
  "device": null,
  "account": null,
  "pairing": {
    "verification_uri_complete": "https://app.deskwink.com/device?code=DW-7KQ4-M2XP",
    "user_code": "DW-7KQ4-M2XP",
    "expires_at": "…"
  },
  "folders": [],
  "capabilities": ["files"],
  "mcp_url": "https://mcp.deskwink.com/mcp",
  "next_step": "Open the pairing link and confirm this computer.",
  "error": null
}

Exit codes

Code	Meaning
`0`	Success. This includes launch returning while it still waits for you to pair.
`1`	Error. Run deskwink doctor for details.
`2`	Wrong command or option.
`4`	status --wait ran out of time.

Where DeskWink keeps its files

System	Folder
Windows	`%LOCALAPPDATA%\DeskWink`
macOS	`~/Library/Application Support/DeskWink`

It holds the settings, the list of shared folders, logs (kept 14 days, metadata only) and backups of files DeskWink changed (kept 7 days). DeskWink never lets your AI read or change this folder.

Not available yet

Commands for updating (deskwink update) and for starting at login (deskwink autostart) are planned but not part of the beta. To update, run npm install -g @deskwink/cli@latest and then deskwink restart. Starting at login is off and cannot be turned on yet.