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.