Start and launch sessions#

Starting in the right shell, directory, and task context removes repeated setup and makes the purpose of a session clear. Linux Public Alpha is available. Use Installation first; portable users must substitute the extracted executable path for automexia. Windows and macOS examples describe planned support, not available packages. Check automexia --help before using advanced options from this broader reference.

Choose a launch approach#

1. Normal application launch#

With the Automexia executable on your PATH, start it with:

automexia

With no custom shell configured, Automexia uses the user's default shell (PowerShell on Windows and the login shell on Unix). A normal launch uses session-only shell integration where supported; it does not rewrite your PowerShell/Bash/Zsh/Fish profile merely because the application opened.

Useful discovery commands are:

automexia --help
automexia --version

Use these before assuming a command from development documentation is present in the particular binary you have.

2. Start in a specific directory#

Use --working-dir / -w when the directory is part of the session you want to create:

automexia --working-dir ~/work/my-project

Automexia validates the path. An invalid working-directory override is rejected with a warning and the safe default is used rather than silently launching in an untrusted/nonexistent location.

When to use this instead of cd#

Use --working-dir when you are launching from a desktop shortcut, script, file manager, or project launcher and already know the desired project root. Use a normal shell cd when you are already working interactively and the directory change is temporary.

For repeated project launchers, prefer a shortcut/script that passes --working-dir over hard-coding project paths into your global Automexia configuration.

3. Start a specific shell or command#

Use -e / --command to replace the configured shell for that launch:

automexia -e pwsh -NoLogo

automexia --working-dir D:\work -e pwsh -NoLogo

automexia --working-dir ~/work -e zsh -l

Important: -e must be the final Automexia option because every value after the program name is passed to that program as an argument.

Temporary override or permanent setting?#

• Use -e when you need a different shell/program for one launch.
• Use [shell] in config.toml when you want that shell as your normal default.
• Use a separate desktop/script launcher when you regularly switch between several fixed launch profiles.

Permanent shell configuration is covered in Configuration and customization.

4. Launch for a single task#

-e can launch a program directly rather than opening the normal interactive shell. For example:

automexia --working-dir ~/work/project -e python

or:

automexia --working-dir D:\work\project -e pwsh -NoLogo

This is useful for a dedicated REPL, monitor, or tool that already owns its own interactive interface. It is less appropriate for a complicated shell command line that depends on pipes, redirection, quoting, environment expansion, or shell aliases: in those cases, start the shell normally and run the command inside it.

Automexia passes an exact program/argument vector; it does not reinterpret the command using shell-string parsing.

5. Create the first configuration#

Automexia works with no config file. Create a starter without overwriting an existing file:

automexia --write-config

You can also choose an explicit file:

automexia --write-config ./automexia.toml

Then open the config using the normal shortcut:

• Windows: Ctrl+,
• Linux/BSD: Ctrl+Shift+,
• macOS: Cmd+,

The config root is:

Start with only the values you need; omitted settings retain tested defaults. See Configuration and customization for a practical workflow and Configuration reference for the complete schema.

6. Optional logging for one launch#

To write an Automexia log file for the current launch:

automexia --enable-log-file

Logs live under the Automexia configuration root. Treat them as potentially sensitive because paths and process diagnostics can reveal local machine information. Use this option when diagnosing a problem, not as a requirement for normal use.

7. Early Access status#

The installation page provides verified Linux x64 and Arm64 packages and release-tested launch steps. This is an Alpha for evaluation; keep a trusted terminal available. Source access is not part of Early Access.

8. Confirm that the session started correctly#

A healthy first session should show:

1. A tab title that identifies the actual shell/profile or WSL distribution.
2. Prompt context and the complete working path before you type the first character.
3. The terminal input row below that context.
4. A pane footer containing operational information such as encoding, newline convention, grid size, and local time when the pane is large enough to show it.
5. Normal shell behavior: history, quoting, completion, scripts, and tools continue to be owned by the shell.

If icon-aware listings or prompt metadata are missing, continue with Shell integration and Troubleshooting.

9. What to learn next#

Once you can open a session, the most important concept is the workspace hierarchy. Read Workspaces, tabs, and panes before building multi-pane layouts; it explains the difference between a top-level tab, a pane-local tab, a fresh split, and a cloned split.