Skip to content

Getting Started

This walkthrough initializes personal configuration, checks the local tools, and installs the minimal managed shell block.

1. Initialize Personal Configuration

Run:

lab init

The command creates ~/.config/lab-env/config.toml, or $XDG_CONFIG_HOME/lab-env/config.toml when XDG_CONFIG_HOME is set. It refuses to replace an existing file and does not alter shell startup files.

Tip

Run lab --config PATH init to test with a temporary configuration or keep separate environments.

2. Check the Local Environment

Inspect the initialized configuration and required local clients:

lab hosts
lab doctor

hosts lists the shared uahpc destination and any hosts in your config. doctor validates configuration, identifies Bash or Zsh, checks Conda initialization, and locates ssh, rsync, scp, and sftp. It never connects to a remote system.

3. Connect and Transfer

Preview commands without connecting:

lab connect uahpc --dry-run
lab pull uahpc results/ ./results/ --dry-run
lab push uahpc input/ work/input/ --dry-run

Add personal destinations under [hosts.NAME] in config.toml as needed. Remove --dry-run to execute the commands. Transfer paths preserve rsync's trailing slash behavior: results/ copies the directory contents, while results copies the directory itself.

4. Preview Shell Integration

Before changing a startup file, inspect the exact paths and managed block:

lab shell preview

For Zsh, the preview normally resolves to:

  • startup file: ~/.zshrc
  • generated file: ~/.config/lab-env/shell/zsh.sh

For Bash, ~/.bashrc holds the interactive setup. Login Bash uses the first existing file among ~/.bash_profile, ~/.bash_login, and ~/.profile; the installer adds a small managed bridge there to source ~/.bashrc unless that profile already does so. This supports both SSH/login shells and interactive non-login shells without duplicating the generated setup.

Override detection when needed:

lab shell preview --shell bash
lab shell preview --shell zsh --rc ./temporary.zshrc

Preview does not write any files.

The generated-file preview includes the configured aliases. By default these are the navigation/listing aliases .., b, l, la, ll, and colorized ls, plus interactive cp, mv, and rm safety aliases. See Configuration to customize or disable defaults.

The same generated file contains managed shell functions. findbig recursively lists files larger than 100 MB beneath the current directory. Pass a different find size to change the threshold:

findbig
findbig 500M
findbig 2G

Use qs to list your jobs; it selects Slurm squeue or PBS qstat based on which scheduler command is available on the system.

5. Install and Activate

lab shell install
source ~/.zshrc  # use ~/.bashrc for Bash
lab shell status

Installation:

  1. Validates config.toml.
  2. Creates a sibling backup such as .zshrc.lab-env.bak.
  3. Adds a marked source block to the interactive startup file and, for Bash, a login bridge when needed. Existing content in either file is preserved.
  4. Writes configured aliases, managed functions, and static state to one generated shell file under ~/.config/lab-env/shell/.

Repeated installation does not duplicate managed blocks. Normal shell startup is quiet and does not launch Python or access the network.

6. Remove the Integration

Remove only the managed block and generated file with:

lab shell uninstall

The command backs up the startup file before editing and preserves all unrelated content.

Try the Workflow Safely

Run the complete workflow against temporary files instead of a real dotfile:

tmpdir=$(mktemp -d)
lab --config "$tmpdir/config.toml" init
lab --config "$tmpdir/config.toml" shell preview --shell zsh --rc "$tmpdir/.zshrc"
lab --config "$tmpdir/config.toml" shell install --shell zsh --rc "$tmpdir/.zshrc"
cat "$tmpdir/.zshrc"

See Configuration to add host records and the Command Reference for command details.