1pub fn print_usage() {
3 println!(
4 r#"Usage: start [options] [--] <command> [args...]
5 start <command> [args...]
6 start --status <uuid> [--output-format <format>]
7 start --list [--running] [--output-format <format>]
8 start --upload-log <uuid-or-session-name>
9 start --stop <uuid-or-session-name>
10 start --terminate <uuid-or-session-name>
11 start --attach <uuid-or-session-name> [--read-only]
12 start --resume <uuid-or-session-name> [-- <command>]
13 start --resume-all [--output-format <format>]
14 start --alias <uuid-or-session-name> <name>
15 start --rename <uuid-or-session-name> <name>
16
17Options:
18 --help, -h Show this usage and exit successfully
19 --isolated, --isolation, -i <env> Run in isolated environment (screen, tmux, docker, ssh)
20 --attached, -a Run in attached mode (foreground)
21 --detached, -d Run in detached mode (background)
22 --session, -s <name> Session name for isolation
23 --session-id <uuid> Session UUID for tracking (auto-generated if not provided)
24 --session-name <uuid> Alias for --session-id
25 --append-attempt Run as the next attempt of the existing --session-id execution
26 --continues <id> Record that this execution continues an earlier one
27 --image <image> Docker image (optional, defaults to OS-matched image)
28 --volume, -v <spec> Docker bind mount/volume host:container[:mode] (repeatable, docker only)
29 --mount <spec> Docker --mount spec (repeatable, docker only)
30 --env, -e <KEY=VALUE> Environment variable for docker container (repeatable, docker only)
31 --label <KEY=VALUE> Container attribution (repeatable, docker only; start-command.* reserved)
32 --privileged Run docker container in privileged mode (docker only)
33 --init, --no-init Run tini as PID 1 to reap orphaned processes (docker only; default START_COMMAND_DOCKER_INIT=1)
34 --network <name> Connect to a named network (repeatable, docker only)
35 --network-alias <alias> Add alias to the first network (repeatable, docker only)
36 --on-kill-resume <N> Resume a killed (exit 137 / OOM) detached docker session up to N times
37 --recovery-command <cmd> Command to run in the same container on such a resume
38 --on-kill-resume-delay <min[-max]> Wait a random number of seconds before each such resume (default 0)
39 --memory <size|N%|MIN%-MAX%> Docker RAM cap; percentages use daemon capacity
40 --memory-reservation <spec> Soft memory limit (Docker size or N%, below --memory)
41 --memory-swap <spec> Combined memory+swap cap (defaults to memory, no extra swap)
42 --cpus <n|N%|MIN%-MAX%> Docker CPU cap; ranges draw once per creation
43 --on-kill-resume-memory <spec> New memory cap before a qualifying OOM recovery
44 --cpu-penalty Enable delayed Docker CPU penalty (default off)
45 --cpu-penalty-cpus <n> Penalty cap (default 2 CPUs)
46 --cpu-penalty-trigger <p%> Busy threshold (default 95% of usable CPUs)
47 --cpu-penalty-trigger-window <d> Fully covered busy window (default 15m)
48 --cpu-penalty-release <p%> Quiet threshold (default 65% of penalty cap)
49 --cpu-penalty-release-window <d> Minimum quiet/capped window (default 15m)
50 Durations accept ms, s, m, h; --status reports penalty state
51 --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
52 --isolated-user, -u [name] Create isolated user with same permissions
53 --keep-user Keep isolated user after command completes
54 --keep-alive, -k Keep isolation environment alive after command exits
55 --auto-remove-docker-container Always remove docker container after exit (compatibility alias)
56 --always-cleanup-container Always remove docker container after exit
57 --keep-container Keep docker container filesystem after exit
58 --keep-container-on-fail Remove successful docker containers, keep failed or OOM-killed ones
59 --shell <shell> Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
60 --use-command-stream Use command-stream library for execution (experimental)
61 --use-formal-ai Perform a natural-language request through Formal AI (experimental)
62 --status <id> Show status of execution by UUID or session name (--output-format: links-notation|json|text)
63 --list List all tracked executions (--output-format: links-notation|json|text)
64 --running With --list, only report executions that are still running
65 --upload-log <id> Upload a sanitized copy of the stored log privately
66 --no-sanitize With --upload-log, explicitly upload without secret redaction
67 --stop <id> Ask a detached isolated execution to stop gracefully
68 --terminate <id> Terminate a detached isolated execution immediately
69 --attach <id> Attach to a running detached isolated execution
70 --read-only With --attach, follow output without sending input
71 --resume <id> Restart a stopped detached execution in the same environment
72 (append -- <command> to run a different command there)
73 --remove-original With legacy snapshot resume, remove the stopped original after launch
74 --remove-original-after <s> Remove it only if the replacement still runs after <s> seconds
75 --snapshot-wait <s> Wait up to <s> seconds for another snapshot on this host (exit 75 after)
76 --snapshot-disk-wait <s> Wait up to <s> seconds for free disk instead of refusing (exit 75 after)
77 --snapshot-size-hint <bytes> Use this writable-layer size instead of docker inspect --size
78 --snapshot-prepare <cmd> docker exec <cmd> in the started original before it is snapshotted
79 --resume-all Re-attach or reconcile every execution still marked running
80 --cleanup Clean up stale "executing" records (crashed/killed processes)
81 --cleanup-dry-run Show stale records that would be cleaned up (without cleaning)
82 --cleanup <id> Remove a Docker execution's containers and snapshot images (never forced)
83 --cleanup-dry-run <id> Show the containers and images --cleanup <id> would remove
84 --alias <id> <name> Add a name the execution can be addressed by
85 --rename <id> <name> Rename the execution, keeping its previous name as an alias
86 --version, -v Show version information
87
88Examples:
89 start echo "Hello World"
90 start bun test
91 start --isolated tmux -- bun start
92 start -i screen -d bun start
93 start --isolated docker -- echo 'hi' # uses OS-matched default image
94 start --isolated docker --image oven/bun:latest -- bun install
95 start -i docker -v ~/.config/gh:/root/.config/gh -e TOKEN=abc -- gh repo list
96 start -i docker --image konard/hive-mind-dind:latest --privileged -- solve ...
97 start -i docker --init -d -- solve ... # tini reaps zombies of long-running tasks
98 start --isolated ssh --endpoint user@remote.server -- ls -la
99 start --isolated-user -- npm test
100 start -u myuser -- npm start
101 start -i screen --isolated-user -- npm test
102 start --status a1b2c3d4-e5f6-7890-abcd-ef1234567890
103 start --status a1b2c3d4 --output-format json
104 start --list
105 start --list --output-format json
106 start --list --running
107 start --upload-log my-screen-session
108 start --stop my-screen-session
109 start --terminate my-screen-session
110 start --attach my-docker-session
111 start --attach my-docker-session --read-only
112 start --resume my-docker-session
113 start --resume my-docker-session -- bash
114 start --resume-all
115 start --session-id <uuid> --append-attempt -- npm test
116 start --continues <uuid> -- npm test
117 start --rename <uuid> nightly-build
118 start -i docker -d --on-kill-resume 3 --recovery-command 'solve --resume' -- solve
119 start -i docker -d --on-kill-resume 3 --on-kill-resume-delay 30-90 -- cargo test
120 start --cleanup-dry-run
121 start --cleanup
122 start --use-formal-ai -- print list of files in current directory
123
124Features:
125 - Logs all output to temporary directory
126 - Displays timestamps and exit codes
127 - Auto-reports failures for NPM packages (when gh is available)
128 - Natural language command aliases (via substitutions.lino)
129 - Process isolation via screen, tmux, or docker"#
130 );
131}