> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envlink.projectinwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run commands

> How envctl exec runs a command in an environment: syncing first, streaming, exit codes, timeouts and results.

```bash theme={null}
envctl exec [--timeout N] [--no-sync] [--dir path] <environment> -- <command> [args...]
```

`<environment>` is a name like `linux-build-3f2a` or an ID like `env_…`. Everything after `--` runs in the environment, in the template's working directory (`/work` for `linux-build`) unless you pass `--dir`.

## What happens

<Steps>
  <Step title="Sync first">
    Your sandbox syncs every share it writes and waits for each receiver's acknowledgement, so the command sees your latest edits. If the environment was just created, a sync waits a few seconds for the tailnet path to form. Skip this with `--no-sync`.
  </Step>

  <Step title="Run and stream">
    The command runs over the tailnet. Standard output and error stream back as they happen, and Ctrl-C stops it.
  </Step>

  <Step title="Results come back">
    Before it reports the exit code, the environment syncs its out shares and waits for your sandbox to acknowledge. Files written to `/work/out` are on your machine when `exec` returns.
  </Step>

  <Step title="Exit">
    `envctl` exits with the command's exit code.
  </Step>
</Steps>

## Shell features

The command isn't run through a shell. For pipes, `&&` or `cd`, wrap it:

```bash theme={null}
envctl exec linux-build-3f2a -- sh -c 'cd /work/api && go test ./... | tee out/test.log'
```

## Timeouts

```bash theme={null}
envctl exec --timeout 300 linux-build-3f2a -- make integration
```

stops the command after 300 seconds and exits with code `124`. Without `--timeout`, a command runs until it finishes or the environment reaches its hard limit.

## Exit codes

| Code | Meaning |
| - | - |
| The command's own | The command ran and exited with it |
| `124` | `--timeout` stopped the command |
| `1` | envctl couldn't run it: the environment isn't reachable, or the first sync failed |
| `2` | The command line was wrong |

## Idle and the log

An environment doesn't go idle while a command runs in it. Every command is recorded with its exit code and duration, and the console shows them on the environment's page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.