terminal-use 0.6.1

Headless virtual terminal for AI agents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

pub async fn run() {
    print!(
        r#"tu ("terminal-use") -- headless virtual terminal for AI agents

Spawn terminal apps, read the screen, send keystrokes. No GUI needed.
Default terminal size: 120x40 (TERM=xterm-256color).
All commands target the "default" session unless --name is given.

COMMANDS:
  run <cmd> [args...]             Spawn a process in a new virtual terminal
    --name <s>                      Session name (default: "default")
    --size <CxR>                    Terminal size (default: 120x40)
    --scrollback <n>                Scrollback lines (default: 1000)
    --env KEY=VAL                   Extra env vars (repeatable)
    --cwd <path>                    Working directory
    --term <TERM>                   TERM value (default: xterm-256color)
    --shell                         Wrap in $SHELL -c "..."
  kill [--name <s>]               Kill process and remove session
  list                            List active sessions
  status [--name <s>]             Session info: pid, alive/exited, exit code, size

  screenshot [--name <s>]         Capture the terminal screen as text
    --png                           Render as a PNG image instead of text
    --output <file>                 Output file path (default: auto temp file)
    --stdout                        Write PNG bytes to stdout (with --png)
    --font <path>                   Optional TTF font file (bundled: JetBrains Mono)
    --font-size <px>                Font size in pixels (default: 14, with --png)
  cursor [--name <s>]             Print cursor position as row,col
  scrollback [--name <s>]         Print scrollback buffer
    --lines <n>                     How many lines (default: all)

  type <text> [--name <s>]        Type literal text
  press <key>... [--name <s>]     Send keystrokes (space-separated)
  paste <text> [--name <s>]       Bracketed paste

  resize <CxR> [--name <s>]      Resize terminal (e.g. 160x50)
  wait [--name <s>]               Wait for a condition
    --stable <ms>                   Screen unchanged for N ms
    --text <regex>                  Regex matches screen content
    --timeout <ms>                  Max wait (default: 5000)

  monitor [--name <s>]            Live read-only view of a session (← → to switch)
  daemon start|stop|status        Manage background daemon
  self update [--check]          Update tu to the latest version

KEYS:
  Letters/symbols    a, Z, !, @            Modifiers       Ctrl+C, Alt+F, Shift+Tab
  Navigation         Up Down Left Right    Ctrl combos     Ctrl+Z, Ctrl+L, Ctrl+D
                     Home End PageUp       Function        F1-F12
                     PageDown
  Editing            Enter Tab Space       Multi-key       press Down Down Down Enter
                     Escape Backspace
                     Delete Insert

OUTPUT:
  Default output is human-readable. Add --json for machine-readable JSON.
  When stdout is not a TTY, --json is auto-selected.

EXAMPLES:
  tu run htop                          Start htop
  tu screenshot                        Read the screen as text
  tu screenshot --png                  PNG to temp file, prints path
  tu screenshot --png -o shot.png      PNG to explicit path
  tu screenshot --png --stdout > s.png PNG bytes to stdout
  tu press F2                          Open htop setup
  tu press Escape : w q Enter          Save and quit vim
  tu type "hello world"                Type text into the terminal
  tu wait --text "Complete" --timeout 10000
  tu monitor                           Watch the session live
  tu kill                              End session
"#
    );
}