Start and launch sessions#

Starting in the right shell, directory, and task context removes repeated setup and makes the purpose of a session clear. Automexia is in development. Use Development setup first and invoke the executable path documented for your build. 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
automexia about
automexia logo

about and logo show the application's identity without starting a terminal session. --help lists the commands in your build and --version reports its 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 a recurring project setup, consider a named profile with a fixed local directory or one that inherits the active pane's directory. A desktop/script launcher remains useful when another application needs to open Automexia directly.

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 named profile when you regularly choose between several session setups from inside Automexia. Ordinary New Tab keeps the configured default.

Permanent shell configuration is covered in Configuration and customization.

4. Reuse a named session setup#

Open the command palette (Ctrl+Shift+P on Linux/Windows or Cmd+Shift+P on macOS), choose New Terminal with Profile, then select a profile and Open in new tab or Open in new window. Choose Settings → Profiles to edit the recipe. For example, a Work profile can open Bash in your home directory with a distinct tab color without changing your Personal tab or the global default. Saved changes apply to future sessions only. The profile guide covers GUI and TOML setup, arguments, directory modes, themes, imports, and launch failures.

5. 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.

6. 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.

7. 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.

8. Development setup#

The setup guide links to the public repository's current development instructions. Check Development status before trying a revision and keep a trusted terminal available.

9. 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.

10. 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.