wdx terminal

Manage terminals: shells that belong to a project and outlive the daemon.

A terminal’s shell runs in its own process, so it keeps running when the daemon restarts or is upgraded. Closing its project stops it, and opening the project again starts a fresh shell.

Command	What it does
`wdx terminal attach`	Show a terminal full-window and type into it, as tmux does
`wdx terminal create`	Create a terminal and start its shell
`wdx terminal get`	Show a terminal
`wdx terminal history`	Print the lines that scrolled off a terminal’s screen
`wdx terminal list`	List terminals
`wdx terminal remove`	Delete a terminal
`wdx terminal send`	Type a message into a running terminal and press Enter
`wdx terminal start`	Start a fresh shell for a terminal that exited, failed or was lost

wdx terminal attach

Show a terminal full-window and type into it, as tmux does.

wdx terminal attach (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--prefix-key <key>] [flags]

The terminal takes the whole window, above a status line, and what you type goes to its shell. C-\ is the prefix for attach’s own keys: C-\ d detaches, leaving the terminal running, and gives the window back as it was; C-\ [ and ] scroll through its history, as PageUp, PageDown and the mouse wheel do at the shell; C-\ ? lists them all. Several clients can attach to one terminal; the last to attach or resize sets its size. It runs in the terminal it was started from, not on stdin and stdout, which print the result when it ends.

Flags

Flag	Default	Description
`--id <id>`		id of the terminal
`--name <name>`		name of the terminal (case-insensitive)
`--prefix-key <key>`	`ctrl-\`	key before attach’s own keys: ctrl-<letter> but i and m, ctrl-\ or ctrl-]
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Attach to a terminal of the project you are in
wdx terminal attach --name server

# With ctrl-] as the prefix
wdx terminal attach --id term-1a2b3c4d --prefix-key ctrl-]

# As JSON once it ends
wdx terminal attach --name server --json

Output

The terminal, once you detach or its shell exits. With --json: {“result”: “detached” or “exited”, “terminal”: {…}}

With --json, result is one of: detached or exited.

Errors

Code	Exit	When
`attach_unsupported`	1	the terminal was started by a wdx too old to attach to
`connection_lost`	3	the connection to the terminal or node ended before it answered
`daemon_unavailable`	3	the daemon is not running or not answering
`holder_version_unsupported`	1	the terminal’s holder and a client on another node speak no version in common: the terminal was started by a wdx too old for relayed clients, or the client’s is too old for the holder
`not_found`	1	nothing has this name or id
`terminal_not_running`	1	the terminal’s shell is not running
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

With --node, also: code_not_set_up, code_wrong, connection_lost, daemon_unavailable, hub_unreachable, hub_version_unsupported, node_key_mismatch, node_not_found, node_offline, node_version_unsupported, not_logged_in, remote_access_off, remote_not_for_agents, route_not_allowed, session_closed, session_required, too_many_streams.

wdx terminal create

Create a terminal and start its shell.

wdx terminal create [--project-id <id> | --project-name <name>] [--name <name>] [flags]

Without a project flag, the terminal belongs to the project the working directory is in, and its shell starts there. With one, it starts in the working directory when that is in the project, else in the project’s clone path. The shell is terminal.shell, your login shell by default.

Terminals get a generated name such as swift-falcon unless --name is given; names have letters, numbers and - only, and are unique within a project.

Flags

Flag	Default	Description
`--name <name>`		name of the terminal (default: a generated one)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --project-id or --project-name

Examples

# Create a terminal in the project you are in
wdx terminal create

# Name it and pick the project
wdx terminal create --project-name app --name server

# As JSON
wdx terminal create --json

Output

The terminal, running. With --json: {“result”: “created”, “terminal”: {…}}

With --json, result is one of: created.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_name`	1	the name is not allowed
`name_taken`	1	something else has this name
`not_found`	1	nothing has this name or id
`project_closed`	1	the project is closed
`start_failed`	3	the holder, the shell or the AI coding agent did not start
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx terminal get

Show a terminal.

wdx terminal get (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [flags]

In any state, with why it failed when it did. Without a project flag, --name is looked up in the project the working directory is in. Nothing is changed.

Flags

Flag	Default	Description
`--id <id>`		id of the terminal
`--name <name>`		name of the terminal (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Show a terminal of the project you are in
wdx terminal get --name server

# By id, as JSON
wdx terminal get --id term-1a2b3c4d --json

Output

The terminal. With --json: {“terminal”: {…}}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx terminal history

Print the lines that scrolled off a terminal’s screen.

wdx terminal history (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--tail <lines> | [--from <line>] [--count <lines>]] [--plain] [flags]

History is kept on disk for the terminal’s life, across restarts of its shell, up to terminal.history_lines, and is there in any state. Lines keep their colors when the output gets color; --plain, or output that is not a terminal, strips them. Lines are numbered from 0, which --from counts in; --count alone starts at the oldest kept.

Flags

Flag	Default	Description
`--count <lines>`	`1000`	lines from `--from` on, or from the oldest kept
`--from <line>`	`0`	number of the first line
`--id <id>`		id of the terminal
`--name <name>`		name of the terminal (case-insensitive)
`--plain`		strip colors and other escape codes
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--tail <lines>`	`0`	the last lines (default: terminal.history_tail)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --tail or --count
at most one of --tail or --from
at most one of --project-id or --project-name

Examples

# The last lines of a terminal of the project you are in
wdx terminal history --name server

# The last 50, without colors
wdx terminal history --name server --tail 50 --plain

# From line 1200 on, as JSON
wdx terminal history --id term-1a2b3c4d --from 1200 --count 100 --json

Output

The lines, oldest first. With --json: {“history”: {“from”: …, “next”: …, “first”: …, “lines”: […]}}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx terminal list

List terminals.

wdx terminal list [--project-id <id> | --project-name <name> | --all] [flags]

Without a flag, the terminals of the project the working directory is in. Every state is listed: a terminal stays until it is removed.

Flags

Flag	Default	Description
`--all`		list the terminals of every project
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --all or --project-id
at most one of --all or --project-name
at most one of --project-id or --project-name

Examples

# The terminals of the project you are in
wdx terminal list

# Every project's, as JSON
wdx terminal list --all --json

Output

The terminals by project, then name; an empty list when there are none. With --json: {“terminals”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx terminal remove

Delete a terminal.

wdx terminal remove (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [--stop-running | --cancel] [flags]

If its shell is running, you are asked whether to stop it, which ends the programs in it; --stop-running and --cancel answer in advance, and with --json one of them is required.

Flags

Flag	Default	Description
`--cancel`		if its shell is running, change nothing without asking
`--id <id>`		id of the terminal
`--name <name>`		name of the terminal (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--stop-running`		if its shell is running, stop it without asking
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --stop-running or --cancel
at most one of --project-id or --project-name
with --json: one of --stop-running or --cancel

Examples

# Remove a terminal of the project you are in
wdx terminal remove --name server

# From a script: stop it if it is running
wdx terminal remove --id term-1a2b3c4d --stop-running --json

Output

The removed terminal, as it was before. With --json: {“result”: “removed”, “terminal”: {…}}

With --json, result is one of: removed.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`terminal_running`	1	the terminal is already starting or running
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx terminal send

Type a message into a running terminal and press Enter.

wdx terminal send (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] --prompt <text> [flags]

The message is queued for the terminal and typed as soon as its shell can take it, in the order sent, into whatever is running there. This does not wait for it to be typed or to run. A message still queued when the shell ends is kept, and waits in wdx message list to be sent again or discarded.

Flags

Flag	Default	Description
`--id <id>`		id of the terminal
`--name <name>`		name of the terminal (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--prompt <text>`		text to type; Enter follows it
`--node <name>`		run the command on the node of this name, another of your account, through a session

--prompt is required
exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Run a command in a terminal of the project you are in
wdx terminal send --name server --prompt make

# By id, as JSON
wdx terminal send --id term-1a2b3c4d --prompt make --json

Output

The terminal the message is queued for. With --json: {“result”: “queued”, “terminal”: {…}}

With --json, result is one of: queued.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`send_failed`	3	the message did not reach the terminal’s holder
`terminal_not_running`	1	the terminal’s shell is not running
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx terminal start

Start a fresh shell for a terminal that exited, failed or was lost.

wdx terminal start (--id <id> | --name <name>) [--project-id <id> | --project-name <name>] [flags]

The terminal keeps its id, name and dir; its scrollback and the programs that ran in it are gone. Terminals stopped by closing their project start again when it is opened.

Flags

Flag	Default	Description
`--id <id>`		id of the terminal
`--name <name>`		name of the terminal (case-insensitive)
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --project-id or --project-name

Examples

# Start a terminal of the project you are in
wdx terminal start --name server

# By id, as JSON
wdx terminal start --id term-1a2b3c4d --json

Output

The terminal, running. With --json: {“result”: “started”, “terminal”: {…}}

With --json, result is one of: started.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`project_closed`	1	the project is closed
`start_failed`	3	the holder, the shell or the AI coding agent did not start
`terminal_running`	1	the terminal is already starting or running
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git