# Commands and files

> Run shell commands, follow long ones, and move files in and out.

## Run a command

```bash
curl -X POST https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/exec \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command": "node --version"}'
```

Commands run with `bash -lc` as the desktop user. If one finishes within `wait_s` (default 25 s), you get `200` with `exit_code`, `stdout` and `stderr`. If not, you get `202` and an exec id.

## Follow a long command

```bash
curl "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/exec/ex_01jb7r2m5k8q3w9x4z6t?until=exit&wait_s=25&tail=true" \
  -H "Authorization: Bearer $KUBI_API_KEY"
```

This waits up to 25 s for the command to end and returns the last part of the output, where errors usually are. A 5-minute build takes about 12 calls. Stop a command with `POST .../exec/{exec_id}/kill`.

Set `"timeout_s": 0` for a command that should run until you kill it, such as a dev server or a desktop app.

Secrets you saved in the dashboard are in every command's environment, and in `/home/user/.config/kubi/secrets.env`. Anything running on the screen, your agent included, can read them, so use keys you can revoke.

## Upload and download

```bash
# upload
curl -X PUT "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/files?path=/home/user/input.csv" \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @input.csv

# download
curl "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/files?path=/home/user/report.pdf" \
  -H "Authorization: Bearer $KUBI_API_KEY" -o report.pdf
```

Files up to 64 MiB. List a folder with `GET /screens/{id}/dir?path=/home/user/Downloads`.

Over MCP, `read_file` and `write_file` move one file up to 64 KiB, as text or base64, so the result fits in an agent app's reply. Move bigger files through the API, the SDK or `exec`.

:::caution
Commands and files need the `exec` permission. A screen holds your logins and keys, so reading its files is as powerful as running commands on it.
:::