# wrap, raw et filter

> tokenade wrap exécute une commande et compacte sa sortie ; raw l'exécute sans y toucher ; filter compacte une sortie déjà capturée.

Source: https://tokenade.net/fr/docs/wrap-raw-filter · Updated: 2026-10-07

`tokenade wrap` exécute une commande shell et renvoie une version compactée de sa sortie, avec le même code de sortie. C'est ce qu'appelle le hook de votre agent pour chaque commande shell, et vous pouvez l'utiliser à la main avec n'importe quel agent. `raw` est l'échappatoire qui exécute une commande sans compaction ; `filter` compacte une sortie capturée plus tôt.

## wrap

```text
tokenade wrap [--shell <posix|powershell|cmd>] [--split-streams] <shell-cmd>
```

Alias : `exec-compact`. Passez la commande en un seul argument entre guillemets : `tokenade wrap 'git log --stat -20'`.

| Option | Effet |
| --- | --- |
| `--shell posix` | Par défaut. `sh -c` (Git Bash sous Windows) |
| `--shell powershell` | `powershell.exe -Command` (ou `pwsh`) |
| `--shell cmd` | `cmd.exe /C` |
| `--split-streams` | Compacte stdout et stderr séparément et rend chacun à son flux, pour que les redirections se comportent comme sans le wrapper. L'ordre chronologique entre les deux flux est perdu |

Sans `--shell`, le shell est déduit de l'environnement, avec `posix` en repli. Précisez-le quand vous enveloppez à la main une commande PowerShell ou cmd.

Ce que fait `wrap`, dans l'ordre :

1. Exécute la commande et capture stdout et stderr ensemble (plafonds : 16 Mo pour stdout, 4 Mo pour stderr).
2. Masque les secrets.
3. Compacte la sortie avec un compacteur qui connaît cette commande, ou qui reconnaît son format (JSON, logs, diffs, tableaux, etc.).
4. Si le résultat reste gros, range la sortie complète sur disque et renvoie un aperçu avec un hash que vous pouvez interroger. Voir [Compaction des sorties et stash](https://tokenade.net/fr/docs/compaction).
5. Sort avec le code de la commande interne (`128 + signal` si elle a été tuée par un signal).

```text
$ tokenade wrap 'seq 1 20000'
[tokenade:seq] 20000 line(s)
1
2
3
…
19999
20000
[tokenade:seq 85479 tokens folded away; the stash holds the COMPLETE output — this blob is ~85690 tokens — too large to dump whole. recover with `tokenade expand-ref f6351f5ead9a` · `--prompt "q1, q2"` to ask (RAG, several at once) · `--grep <pat>` exact lines. …]
```

```text
$ tokenade wrap 'exit 7'; echo $?
7
```

### Piège : stderr est fusionné

`wrap` fusionne stderr dans stdout avant de compacter. `tokenade wrap 'cmd' 2>err.log` écrit donc un `err.log` vide. Faites la redirection dans la commande enveloppée (`tokenade wrap 'cmd 2>err.log'`) ou utilisez `--split-streams`.

## raw

```text
tokenade raw <command> [args...]
tokenade raw '<command line>'
```

Alias : `bypass`, `noproxy`. Exécute la commande sans compaction et définit `TOKENADE_HOOK_DISABLED=1` pour que les hooks de l'agent la laissent passer aussi. Les flux de sortie sont hérités, le code de sortie est celui de la commande, et rien n'est écrit dans le registre des économies.

Vous n'en avez généralement pas besoin. Si vous avez déjà lancé une commande via Tokenade et qu'il vous faut les octets exacts, `tokenade expand-ref <hash>` les rend depuis le stash, instantanément, sans rien relancer. `raw` sert à ce que le stash ne peut pas fournir : relancer sans compaction, exécuter en interactif, ou déboguer un compacteur.

Pour les commandes dont la sortie se replie bien (`grep`, `rg`, `ag`, `find`, `ls`, `wc`, `head`, `tail`, `awk`, `sed`, `cat`), `raw` refuse et sort en `2`, car relancer dépenserait une seconde fois les tokens de l'appel d'origine :

```text
$ tokenade raw ls
[tokenade] refusing bypass for `ls` — re-running it would spend the original call's tokens again.
  Most of what you want is already recoverable: `tokenade expand-ref <hash>` …
```

Forcez avec `TOKENADE_FORCE_BYPASS=1 tokenade raw …` quand vous avez vraiment besoin du flux d'origine.

À partir du 10e contournement en 24 heures (`raw`, ou tout hook sauté via `TOKENADE_HOOK_DISABLED=1`, comptés dans `~/.tokenade/bypass-counter`), chaque contournement affiche un rappel d'une ligne sur stderr qui renvoie vers `expand-ref`. Ce rappel ne peut pas être désactivé.

## filter

```text
<cmd> 2>&1 | tokenade filter <argv...>
```

Compacte l'entrée standard comme si elle venait de la commande indiquée. Pratique quand la sortie est déjà capturée :

```bash
cargo build 2>&1 | tokenade filter cargo build
cat /tmp/log.txt | tokenade filter git log
```

| Option | Effet |
| --- | --- |
| `--deliver` | Lance aussi la seconde étape : range dans le stash ce qui reste trop gros et indique comment retrouver ce qui a été retiré, exactement comme `wrap` |

Sans `--deliver`, `filter` n'applique que le compacteur de la commande et ne range rien dans le stash. Sur une sortie que ce compacteur laisse telle quelle, il renvoie l'entrée inchangée là où `wrap` la replierait quand même. `tokenade read -` est encore différent : il détecte le format sans indication de commande.

## Envelopper automatiquement dans votre shell

`tokenade shell-init` affiche un fragment de shell qui fait passer les commandes bavardes par `tokenade wrap` quand l'entrée standard n'est pas un terminal, autrement dit pour les agents, pas quand vous tapez vous-même. Elle couvre les commandes que Tokenade sait compacter, limitées à ce qui est réellement présent dans votre `PATH`.

```bash
eval "$(tokenade shell-init)"                 # sh, bash, zsh
tokenade shell-init --shell fish | source      # fish
```

```powershell
Invoke-Expression (& tokenade shell-init --shell powershell | Out-String)
```

Options : `--shell sh|bash|zsh|fish|powershell|nushell|csh|cmd`, `--all` (sans filtre sur le `PATH`). Sous csh/tcsh et cmd.exe, les alias passent par `tokenade shellwrap`, qui laisse passer dans un terminal et enveloppe sinon. `tokenade install` met cela en place pour vous ; il n'est utile à la main que pour un agent que Tokenade ne peut pas brancher par hooks.

## Voir aussi

- [Compaction des sorties et stash](https://tokenade.net/fr/docs/compaction)
- [Récupérer une sortie repliée](https://tokenade.net/fr/docs/expand-ref-disclose)
- [Comment les hooks interceptent les appels d'outils](https://tokenade.net/fr/docs/hooks)
- [Lancer des scripts avec execute](https://tokenade.net/fr/docs/execute)
