# Commands, files and CI

> Run commands with their output as it comes, leave long jobs and servers running in the background, copy files in and out with cloudex cp, and run CI jobs in a fresh sandbox with cloudex run.

Four commands cover scripts, CI jobs and agents that drive a sandbox from outside:

```sh
cloudex exec -- npm test                     # run a command; output as it comes
cloudex exec -d -- npm run dev               # leave one running in the background
cloudex cp ./data :data                      # copy files in, or out
cloudex run -- npm test                      # a fresh sandbox with this directory, then gone
```

The [API](https://cloudex.build/docs/api.md#commands) and the [SDKs](https://cloudex.build/docs/sdk.md) do the same.

## Run a command

```sh
cloudex exec -- npm test
cloudex exec web -- 'cd app && git status'
cloudex exec -- python3 -c 'print(42)'
cloudex exec --root -- apt-get install -y ripgrep
cloudex exec --cwd app --timeout 30m -- make
```

`cloudex exec` runs a command with `bash -lc` in the sandbox, as the `cloudex` user in its home directory, as an SSH login would. Its standard output and standard error come back as they're printed, and `cloudex exec` exits with the command's exit code.

One argument after `--` is a shell command line, so `&&`, pipes and globs work in it. Several arguments are one command and its arguments, each kept whole, the way `python3 -c 'print(42)'` reads. Without `--`, every argument is the command and the current sandbox runs it.

| Flag | Default | Effect |
|---|---|---|
| `--root` | off | Run as root |
| `--cwd` | the home directory | Working directory; a relative one starts in the home directory |
| `--timeout` | `10m` | Stop the command after this long, at most `1h` |
| `-d`, `--detach` | off | Start the command in the background; see below |

A timeout, or Ctrl-C, stops the command and everything it started. `exec` has no terminal, and it doesn't send standard input, so a command that reads it sees it end at once. Use `cloudex ssh` for interactive programs. Its output is text, and bytes that aren't valid UTF-8 come back as U+FFFD. To put a file in a sandbox, or to get a binary file out, use [`cloudex cp`](#copy-files). With `--json`, it waits and prints `exitCode`, `stdout`, `stderr`, `timedOut` and `ms`, with each stream cut at 1 MiB.

## Background commands

```sh
cloudex exec -d -- npm run dev               # start; prints its id
cloudex exec -d --timeout 2h -- make all     # stop it after 2 hours
cloudex commands                             # list them
cloudex commands logs -f cm-1a2b3c4d         # follow its output to the end
cloudex commands kill cm-1a2b3c4d            # stop it and what it started
cloudex commands rm cm-1a2b3c4d              # remove its record and output
```

`cloudex exec -d` starts a command and returns. The command keeps running in the sandbox with no time limit, unless `--timeout` sets one, and a dropped connection doesn't stop it. Its standard output and standard error go to one log on the sandbox's disk, which `cloudex commands logs` prints; with `-f` it keeps printing until the command ends and then exits with its exit code, or, for a command stopped by a signal, 128 plus the signal's number, as bash does. Ctrl-C stops following, not the command.

`cloudex commands` shows each command's state:

| State | Means |
|---|---|
| `running` | Still running |
| `exited N` | Ended by itself with exit code N |
| `killed (TERM)` | Stopped by a signal, from `cloudex commands kill` or anything else |
| `timed out` | Stopped by its `--timeout` |
| `lost` | The sandbox stopped while it ran |

A stop ends every running command, and a resume doesn't start them again; put servers you want after every start in [`~/.cloudex/start`](https://cloudex.build/docs/sandboxes.md#start-commands). The records and logs stay until `cloudex commands rm` removes them, and [forks](https://cloudex.build/docs/forks.md) get a copy. [Named saves](https://cloudex.build/docs/saves.md) leave them out.

A background command that has printed something in the last 10 minutes counts as activity for [idle stop](https://cloudex.build/docs/sandboxes.md#idle-stop), like an agent; one that stays quiet longer lets the sandbox stop. Cloudflare's [6-hour limit](https://cloudex.build/docs/sandboxes.md#the-6-hour-limit) still applies to jobs that run longer, except on a [node](https://cloudex.build/docs/nodes.md), which has none.

## Copy files

```sh
cloudex cp report.csv :data/                 # into the current sandbox's ~/data
cloudex cp ./site web:/srv/site              # a directory
cloudex cp :app/dist ./dist                  # out of the current sandbox
cloudex cp web:/var/log/app.log -            # to standard output
echo hello | cloudex cp - :hello.txt         # from standard input
```

Name a path in a sandbox as `SANDBOX:PATH`, or `:PATH` for the current sandbox. Relative paths there start in the home directory. It works like `cp -r`: when the destination is a directory that exists, or ends with `/`, what you copy goes inside it; otherwise it's created with that name. Files keep their permissions, and directories keep their symlinks. A local path that is a symlink to a directory copies that directory. A download makes the local directories it needs. `-r`, `-R` and `-a` are accepted and change nothing, since directories always copy whole.

A download can't reach outside where you put it: it never writes through a symlink, leaves out symlinks that point outside it, and leaves out `.git` directories, whose hooks and settings could run commands on your computer. To bring a sandbox's commits home, push them from the sandbox. A download also leaves out hard links, devices, and files the `cloudex` user can't read, which `--root` reads. The summary that `cloudex cp` prints on standard error counts what it left out, except the files it couldn't read.

Files are read and written as the `cloudex` user, so the sandbox's permissions apply; `--root` reads and writes as root. A file is replaced whole, so nothing reads half of it. Cloudflare limits an upload to 100 MB at a time, compressed. For more, or to sync a folder repeatedly, use `rsync` through [ssh-config](https://cloudex.build/docs/connect.md#scp-rsync-and-editors).

## CI jobs: cloudex run

```sh
cloudex run -- npm test
cloudex run --from node-base --out dist -- 'npm ci && npm run build'
cloudex run --env CI=1 --keep-on-failure -- make check
```

`cloudex run` does a whole job in one command. It:

1. Starts a sandbox.
2. Copies the current directory into it.
3. Runs the command there, printing its output as it comes.
4. Copies back what `--out` names.
5. Deletes the sandbox.

It exits with the command's exit code, so a CI step fails when the command does. What `--out` copies back leaves out the same things as a [download](#copy-files).

In a git repository it copies the files git would commit: tracked files, and new ones that `.gitignore` doesn't exclude, but not `.git` itself. Elsewhere it copies everything under `--dir`. They go to `~/<the directory's name>`, where the command runs.

`--from` starts from a [named save](https://cloudex.build/docs/saves.md), or a fork of a sandbox, instead of the plain image. Set up a sandbox once with your tools and dependencies, save it, and each run starts from that save with your latest files copied over it:

```sh
cloudex new --name node-base
cloudex exec node-base -- 'git clone https://github.com/you/app && cd app && npm ci'
cloudex save node-base node-base
cloudex run --from node-base --workdir app -- npm test   # in ~/app, where node_modules is
```

The command runs as a [background command](#background-commands), so it has no time limit unless you set `--timeout`, and a dropped connection doesn't stop it; `run` reconnects for up to two minutes. Ctrl-C stops the command and deletes the sandbox; a second Ctrl-C quits at once and leaves the sandbox. A command stopped by its `--timeout` makes `run` exit with 124.

| Flag | Default | Effect |
|---|---|---|
| `--from` | the image | Start from this named save, or a fork of this sandbox |
| `--dir` | `.` | The directory to copy |
| `--workdir` | `~/<its name>` | Where the files go, and the command runs |
| `--no-upload` | off | Copy nothing |
| `--out` | none | A file or directory to copy back after, relative to the workdir; it lands at the same place under `--dir`. Repeatable. |
| `--env` | none | `NAME=VALUE`, repeatable. `--env-file` reads a file of them. |
| `--timeout` | none | Stop the command after this long |
| `--keep` | off | Keep the sandbox after |
| `--keep-on-failure` | off | Keep it when the command fails or is stopped, to look around with `cloudex ssh` |
| `--size`, `--name`, `--idle` | as `cloudex new` | The sandbox's size, name and idle stop |
| `--on` | Cloudflare | Run it on one of your [nodes](https://cloudex.build/docs/nodes.md). An own-only token can use only nodes with Sysbox. |

In GitHub Actions, give the job your deployment's URL and a [token](https://cloudex.build/docs/tokens.md) limited to its own sandboxes as secrets: `cloudex tokens create github-actions --own --expires 90d` makes one, and `cloudex status` prints the URL.

```yaml
- run: curl -fsSL https://cloudex.build/install | CLOUDEX_INSTALL_DIR="$HOME/.local/bin" sh
- run: ~/.local/bin/cloudex run --from node-base -- npm test
  env:
    CLOUDEX_API_URL: ${{ secrets.CLOUDEX_API_URL }}
    CLOUDEX_API_KEY: ${{ secrets.CLOUDEX_TOKEN }}
```
