# Run scripts with execute

> tokenade execute runs a short script and returns only its stdout, redacted and compacted, so raw data never enters your agent's context.

Source: https://tokenade.net/en/docs/execute · Updated: 2026-10-07

`tokenade execute` runs a short script and hands back only what it prints. Use it when the answer is a derived value (a count, a filter, a sum) and the data it comes from would be expensive to put in your agent's context. Aliases: `exec`, `run-script`.

## Usage

```text
tokenade execute --lang <name> [--script CODE | -] [--cwd DIR] \
               [--timeout SECS] [--cap BYTES] [--no-compact] [--no-redact]
tokenade execute --list   # show supported interpreters
```

| Flag | Default | Effect |
| --- | --- | --- |
| `--lang <name>` | required | `bash`, `sh`, `python`, `node`, `ruby`, `awk`, `jq`, `perl` |
| `--script CODE` | | Source to run. `--script -` reads the script from stdin |
| `--script-file F` | | Read the script from a file, with no shell quoting to get wrong |
| `--cwd DIR` | current directory | Working directory |
| `--timeout SECS` | `30` (max `600`) | Kill the script after this many seconds |
| `--cap BYTES` | 1 MiB (max 16 MiB) | Stdout cap |
| `--no-compact` | off | Skip the post-run compactor |
| `--no-redact` | off | Skip secret redaction (not recommended) |
| `--sandbox` | off | Run under bubblewrap (`bwrap`): whole filesystem read-only, a fresh writable `/tmp`, no network. Also `TOKENADE_EXEC_SANDBOX=1` |
| `--sandbox-net` | off | Allow network inside the sandbox. Also `TOKENADE_EXEC_SANDBOX_NET=1` |
| `--list` | | Print supported interpreters and exit |
| `--json` | | With `--list`, print the interpreters as JSON |

## What "sandbox" means here

By default the script runs in a separate process with a scrubbed environment, a timeout and output caps. It is not a syscall jail: it runs as you, with your filesystem and your network. Treat a script here exactly as you would treat running it in your own shell.

`--sandbox` adds real confinement on Linux through bubblewrap. If `bwrap` is not installed, `execute` refuses to run rather than run unconfined.

## Examples

```text
$ tokenade execute --list
Available interpreters:
  bash     (binary: bash)
  sh       (binary: sh)
  python   (binary: python3)
  node     (binary: node)
  ruby     (binary: ruby)
  awk      (binary: awk)
  jq       (binary: jq)
  perl     (binary: perl)
```

```text
$ tokenade execute --lang python --script 'print(sum(range(101)))'
5050
```

Data you pipe in reaches the script's stdin, so a large output is reduced where it is produced:

```text
$ cat orders.json | tokenade execute --lang python \
    --script 'import json,sys; print(len(json.load(sys.stdin)["items"]))'
2
```

A long or quote-heavy script is easier from a file:

```bash
tokenade execute --lang python --script-file ./count_errors.py < build.log
```

## Exit codes

| Code | Meaning |
| --- | --- |
| Script's own code | `execute` returns the exit code of the script (`sys.exit(3)` gives `3`) |
| `255` | Timed out. Stdout produced before the kill is kept |
| `127` | Unknown `--lang` |

On timeout the message says how to raise it:

```text
tokenade execute: timed out after 1.01s (ceiling 1s). Raise it with `--timeout <secs>` (max 600), or narrow the script. …
```

## Gotchas

- **jq runs with `-n`.** Read piped data explicitly with `input`: `--script 'input | .items | length'`. A plain `.items | length` sees no input and prints `0`.
- `--script -` uses stdin for the script itself, so you cannot also pipe data in. The same applies to a `bash` or `sh` script over 64 KiB. Use `--script-file` instead.
- Output is redacted for secrets by default, then compacted and capped. If the result looks trimmed, raise `--cap` or narrow what the script prints.
- Keep scripts short. `execute` is for throwaway computation; code you will edit and rerun belongs in a real file.

## Related

- [wrap, raw and filter](https://tokenade.net/en/docs/wrap-raw-filter)
- [Output compaction and the stash](https://tokenade.net/en/docs/compaction)
- [Get folded output back](https://tokenade.net/en/docs/expand-ref-disclose)
