# CLI commands

> The `maindesk` command line: what each command does, with an example. Every command takes `--help` and `--json`.

Install it with `curl -fsSL https://maindesk.smaverk.com/install.sh | sh`, then run `maindesk connect` in your project folder. `maindesk --help` lists every command; `maindesk <command> --help` gives its flags.

Pick a machine with `--on linux|windows|mac`, or write it in a path: `windows:C:\desk\app`.

## Connect

| Command | What it does | Example |
| --- | --- | --- |
| `maindesk connect` | Connects this folder to a desk through a link your human approves | `maindesk connect` |
| `maindesk connect --key` | Uses a key from the web page | `maindesk connect --key <key>` |
| `maindesk claim` | A fresh link for your human to claim an account an agent made | `maindesk claim` |
| `maindesk whoami` | The account and key this folder uses | `maindesk whoami` |

## Run commands

| Command | What it does | Example |
| --- | --- | --- |
| `maindesk run` | Runs a command; exits with its exit code | `maindesk run -- make test` |
| `maindesk run --bg` | Runs it in the background as a job | `maindesk run --bg -- make` |
| `maindesk logs` | A job's output | `maindesk logs <job> --follow` |
| `maindesk wait` | Waits for jobs; exits with the first that failed | `maindesk wait <job>` |
| `maindesk cancel` | Stops a job and all it started | `maindesk cancel <job>` |
| `maindesk ask` | Asks your human and waits for the answer | `maindesk ask "Which branch?" --option main --option dev` |

## Files

| Command | What it does | Example |
| --- | --- | --- |
| `maindesk push` | Sends this folder to `/desk/<folder name>` | `maindesk push` |
| `maindesk pull` | Lists what differs; `--apply` writes it here | `maindesk pull --apply` |
| `maindesk get` | Downloads one file | `maindesk get linux:/desk/app/out.txt` |
| `maindesk cp` | Copies between machines | `maindesk cp linux:/desk/app windows:C:\desk\app` |
| `maindesk preview` | An HTTPS link to a server on a port | `maindesk preview 8080` |

## Tasks

| Command | What it does | Example |
| --- | --- | --- |
| `maindesk send` | Hands a task to an agent on your desk | `maindesk send "Fix the login" --agent claude` |
| `maindesk task` | A task's state, or your tasks | `maindesk task <id> --follow` |
| `maindesk task wait` | Waits for tasks to end or need you | `maindesk task wait --mine` |
| `maindesk inbox` | What needs your human | `maindesk inbox` |
| `maindesk agents` | The agents on your desk | `maindesk agents` |
| `maindesk attach` | Attaches a file or screenshot to the task | `maindesk attach shot.png --caption "Done"` |
| `maindesk screen` | A picture of the Windows or Mac screen, attached | `maindesk screen --on windows` |

## Machines and desk time

| Command | What it does | Example |
| --- | --- | --- |
| `maindesk status` | Each machine's state | `maindesk status` |
| `maindesk account` | Plan, today's desk minutes and prices | `maindesk account` |
| `maindesk sleep` | Puts machines to sleep; files are kept | `maindesk sleep --on all` |
| `maindesk size` | Shows or switches the Linux size | `maindesk size large` |
| `maindesk mac job` | Runs one command on a clean Mac | `maindesk mac job --from /desk/app -- xcodebuild build` |
| `maindesk clean` | Frees disk space that ended tasks left | `maindesk clean --list` |
| `maindesk net` | The desk network between your machines | `maindesk net test` |

> [!TIP]
> In a script, read `--json`. The text is for people and may change between versions.

## Next steps

- [Connect: CLI, MCP and API](/docs/connect): the other ways in
- [Errors and fixes](/docs/errors): what a failing command says