# Commands

You run shell commands on a computer with `exec`. Its output streams back while the command runs, so you can show it to a person or pass it to a model before the command ends.

## Run a command

`output()` waits for the command to end and returns what it printed and how it ended.

```rust
let output = client
    .computer(id)
    .exec("bun test")
    .output()
    .await?;
```

## Stream the output

An `Exec` is the command while it runs:

| Method          | What it does                                          |
| --------------- | ----------------------------------------------------- |
| `stdout()`      | Streams standard output as the command writes it.     |
| `stderr()`      | Streams standard error as the command writes it.      |
| `write(bytes)`  | Sends bytes to the command's standard input.          |
| `close_stdin()` | Ends its standard input.                              |
| `kill(signal)`  | Sends the command a signal.                           |
| `wait()`        | Waits for the command to end and returns its outcome. |

There is no terminal resource. Interactive programs take their input through `write` and `close_stdin`.

## Options

| Option       | What it does                                                              |
| ------------ | ------------------------------------------------------------------------- |
| `cwd`        | The directory the command starts in.                                      |
| `user`       | The user it runs as.                                                      |
| `env`        | Environment variables for this command only.                              |
| `secrets`    | Secrets the command can use. Inline values stay in memory, never on disk. |
| `timeout`    | How long it may run. A command that runs longer ends as `TimedOut`.       |
| `background` | Returns at once instead of waiting, so the command keeps running alone.   |

Each command starts a new shell. A directory you change to or a variable you export in one command is gone in the next, so set `cwd` and `env`, or join the steps in one command with `&&`.

## Long-running commands

Set `background` for builds, servers and test suites that outlast the request. `execs()` finds them again:

| Method             | What it does                                                  |
| ------------------ | ------------------------------------------------------------- |
| `list(query)`      | Lists the computer's commands.                                |
| `get(id)`          | Returns one command's status, start time and end time.        |
| `attach(id)`       | Reconnects to a running command and streams its output again. |
| `kill(id, signal)` | Sends a running command a signal.                             |

A command's status is `Running`, `Exited` with its exit code, `Killed` with the signal, or `TimedOut`.

## Next steps

* [Desktop](/computer/concepts/desktop): the mouse, keyboard and screen of the same computer
* [Run an agent](/computer/guides/run-an-agent): a full task from start to finish