The manual page

Astrum's commands, options, files and environment variables, as the manual page gives them.

This is the manual page that man astrum shows and astrum man prints. The install script puts it where man finds it.

Name

astrum - a persistent terminal with tabs, mouse support and a built-in AI agent

Synopsis

astrum [-s SESSION] [COMMAND]

Description

astrum runs inside the terminal you already use. It shows your own shell with a tab bar above it and a status bar below, keeps your shells running in the background when the window is closed, and has an agent that works in the same shell you do.

Run with no command, it attaches to the session, starting it first if it is not running. Everything on screen can be clicked; ≡ menu in the status bar lists every action with the key that does the same. The prefix key is Ctrl+B unless changed.

Commands

attach
Attach to the session, starting it if needed. This is what happens when no command is given.
ls
List running sessions, and stopped ones whose tabs would come back.
kill [--all] [--forget]
Stop a session and close its shells. Its tabs come back the next time it is started, unless --forget is given. --all stops every session.
config [--init]
Show where the config file is. --init writes a commented starter file there.
themes [--json]
List the color themes, the built-in ones and your own; --json gives their colors as well.
keys [--json]
List what Astrum's keys do, with the keys each action has now; --json as JSON.
reload
Have a running session read its settings, providers and keys again, passing along the key variables of the shell it is run from.
layouts
List the layouts there are.
run [--new-tab | --split right|down | --float] [--wait] [--keep] [--focus] -- COMMAND
Open a pane in a running session and run a command in it, in the folder this is run from; prints the pane's id. --wait waits for it to end and exits with its exit code.
send [--pane ID] [--enter] TEXT
Type text into a pane of a running session. It reaches the pane's program, never the agent.
capture [--pane ID] [--history]
Print what a pane shows, or everything it has kept.
list [--json]
List a running session's tabs and panes, with each pane's id, folder and what it is doing.
status STATE [MESSAGE]
Say how a script is doing, for the pane it runs in: working, done, blocked, error, idle or clear.
upgrade [--all] [--force] [--fetch|--no-fetch]
Move a running session onto the Astrum that is installed, keeping everything in it running: its shells and the programs in them, what each pane shows, its tabs and conversations. First, a newer release is looked for; at a terminal, installing it is offered. --all moves every running session; --force moves one that already runs this version; --fetch installs a newer release without asking; --no-fetch does not look for one.
service install|uninstall|status
Run the session under the system's service manager (launchd on macOS, the systemd user manager on Linux), so that it starts at login and is started again if it stops. install --print shows what would be written without doing it.
completions bash|zsh|fish
Print a completion script for that shell.
man
Print this manual page.

Options

-s, --session NAME
The session to act on. Each session has its own tabs. The default is default.
--layout NAME
Open a layout in the session as this terminal attaches: the tabs, splits and commands of ~/.config/astrum/layouts/NAME.toml.
--watch
Attach to a running session to watch only. Nothing typed, pasted or clicked in this terminal reaches the session; it can look at another tab and leave. It starts no session.
-h, --help
Show help.
-V, --version
Show the version.

Files

~/.config/astrum/config.toml
Settings. Read again whenever it is saved.
~/.config/astrum/state.toml
What was chosen inside Astrum; takes the place of the config file for those settings.
~/.local/share/astrum/
Saved sessions, saved conversations, the shell integration, and builds of Astrum fetched to copy to other machines.

Environment

ASTRUM_CONFIG_DIR, ASTRUM_DATA_DIR, ASTRUM_RUNTIME_DIR
Other places for the settings, the saved data, and the session sockets.
ASTRUM_CLIPBOARD_TOOL, ASTRUM_OPEN_TOOL
The program copied text is handed to, and the one a link is opened with; none for neither.
ASTRUM_DOWNLOAD_BASE
Where the release files are, in place of GitHub, when Astrum is copied to another machine for a tab there: an https:// address, or file:// and a directory. The same as download_base in the config file.
ASTRUM_NOTIFY
How this terminal is sent a notification when an agent in a tab not in front, or a pane nobody can see, needs you or has finished: osc9, osc99, osc777, or none for a bell. Unset, it is chosen from the terminal.
ASTRUM_SSH
The program run in place of ssh(1) to reach another machine.
ASTRUM_IMAGES
The ways this terminal can show a picture, where Astrum is wrong about it: kitty, iterm, sixel, several with commas, or none.

See also

The README and the changelog, at the project's page.