Repair the current install
mars path setup
hash -r
mars version
Use hash -r when the current shell cached an older
command path. Open a new terminal when the reload hint asks for it.
Developer shell contract
Make mars available, current, and tab-completable.
Shell integration has two separate jobs. PATH setup makes a new
terminal able to find the installed mars command.
Completion scripts teach Bash, Zsh, Fish, and PowerShell the
current command tree, flags, and subcommands. Treat them
separately when installing, updating, or troubleshooting.
Mental Model
| Surface | Command | What it changes | What it does not do |
|---|---|---|---|
| PATH setup | mars path setup |
Writes an idempotent shell profile snippet so future terminals can resolve the installed command directory. | It does not install tab completion scripts and it does not reload every already-open shell automatically. |
| Shell completions | mars completion <shell> |
Prints a generated completion script for Bash, Zsh, Fish, or PowerShell. | It does not decide where to persist the script. Users install it using the shell-specific recipe. |
| Command cache | hash -r or a fresh terminal |
Clears stale command lookup state in many POSIX shells after reinstalling or moving binaries. | It does not change profile files or choose which installed binary should win on PATH. |
Fast diagnosis:
if
mars is missing, think PATH. If mars version
is old, think command cache or multiple binaries. If tab completion
is missing, think completion script installation.
Install Paths
Source installs and packaged updates both end by making the
installed command directory available to new shells. The directory
can be resolved from the running executable, an explicit
--install-dir, go env GOBIN, or the first
GOPATH/bin entry.
| Path | Command | Shell integration result |
|---|---|---|
| Source install | make install |
Installs the development binary into the Go bin directory and runs PATH setup through the installed binary. |
| Source update | make update-tool |
Fast-forwards a clean checkout, reinstalls, runs PATH setup, and prints the installed version. |
| Packaged update | mars update tool |
Replaces the installed binary and checks PATH setup for the chosen install directory. |
| One-off binary | go build -o build/mars ./cmd/mars |
Creates a local binary. PATH setup is separate unless you intentionally point shells at that directory. |
Avoid stale source-root binaries:
use
go build -o build/mars ./cmd/mars for one-off
builds. Avoid go build ./cmd/mars; ./mars ..., because
a failed build can still leave an older ./mars binary
ready to run.
PATH Setup
mars path setup writes a managed block or shell-specific
file for the current user. It is safe to run repeatedly: when the
target POSIX-style or Csh/Tcsh profile already contains the managed
MARS PATH entry, the command reports that no profile change is
needed. Fish may rewrite the same stable mars.fish
content, but the resulting PATH setup remains duplicate-safe.
Preview without writing
mars path setup --dry-run
mars path setup --dry-run --jsonUse dry-run mode on managed machines or before changing a profile file you do not normally edit.
Configure a known shell or directory
mars path setup --shell zsh
mars path setup --install-dir "$HOME/go/bin"
mars path setup --shell fish --install-dir "$HOME/go/bin"
--shell accepts a shell path or shell name. Use it
when $SHELL does not match the terminal users open.
| Flag | Use |
|---|---|
--install-dir <dir> | Choose the directory containing the intended mars binary. |
--shell <name-or-path> | Override shell detection. Defaults to $SHELL. |
--dry-run | Report the planned setup without writing profile files. |
--json | Emit structured fields such as install directory, shell, profile path, changed state, and reload hint. |
Profile Files
PATH setup chooses one user profile destination based on shell detection. If a shell is unsupported, the command reports the install directory and asks you to add it to PATH manually.
| Detected shell | Profile target | Reload hint |
|---|---|---|
fish | ~/.config/fish/conf.d/mars.fish | Open a new terminal or run exec fish. |
zsh | ~/.zshrc | Open a new terminal or run source ~/.zshrc. |
bash on macOS | ~/.bash_profile when it already exists, otherwise ~/.bashrc. | Open a new terminal or source the chosen file. |
bash on Linux | ~/.bashrc | Open a new terminal or run source ~/.bashrc. |
sh, dash, ksh, mksh | ~/.profile | Open a new terminal or run . ~/.profile. |
csh, tcsh | ~/.cshrc | Open a new terminal or run source ~/.cshrc. |
POSIX-style profiles use a managed block marked
# >>> mars PATH >>> and
# <<< mars PATH <<<. Fish receives a
managed mars.fish file. Legacy
mars-harness managed entries are ignored or replaced
instead of being treated as current MARS setup; Fish rewrites the
current mars.fish file and removes the legacy Fish file
when present.
Shell Completions
mars completion is generated from the live Cobra
command tree. Regenerate completions after updating MARS when you
want newly added commands or flags to appear in tab completion.
Every completion subcommand supports --no-descriptions.
| Shell | Current session | Persistent install |
|---|---|---|
| Bash | source <(mars completion bash) |
mars completion bash > /etc/bash_completion.d/mars on Linux, or mars completion bash > $(brew --prefix)/etc/bash_completion.d/mars on macOS with Homebrew bash-completion. |
| Zsh | source <(mars completion zsh) |
mars completion zsh > "${fpath[1]}/_mars" on Linux, or mars completion zsh > $(brew --prefix)/share/zsh/site-functions/_mars on macOS. |
| Fish | mars completion fish | source |
mars completion fish > ~/.config/fish/completions/mars.fish. |
| PowerShell | mars completion powershell | Out-String | Invoke-Expression |
Add the output of mars completion powershell to your PowerShell profile. |
Zsh prerequisite:
if completion is not enabled, add
autoload -U compinit; compinit
to ~/.zshrc, then start a new shell.
Bash prerequisite:
Bash completion depends on the
bash-completion package.
Install it with your operating system package manager before using
the persistent recipe.
Automation
Agents and scripts should prefer explicit shell, explicit install
directory, dry-run previews, and JSON output. That keeps shell
integration deterministic even when the process environment has a
different $SHELL than the human terminal.
Preview a managed workstation change
mars path setup --shell zsh --install-dir "$HOME/go/bin" --dry-run --jsonRead profile_path, changed, and reload_hint before applying.
Apply after a source install
make install
mars path setup --shell zsh --json
mars versionmake install already runs PATH setup, but an explicit command is useful in automated diagnostics.
Regenerate completions after update
mars update tool
mars completion zsh > "$(brew --prefix)/share/zsh/site-functions/_mars"Run the shell-specific command that matches your completion installation path.
Verification
Verify command discovery, binary freshness, shell profile state, and completion generation separately. This avoids chasing the wrong subsystem when one part works and another part does not.
| Question | Command | Expected signal |
|---|---|---|
| Can this shell find MARS? | command -v mars | An absolute path to the intended installed binary. |
| Which binary is running? | mars version | The expected version, OS, architecture, commit, and build date. |
| Is PATH setup needed? | mars path setup --dry-run --json | profile_already_configured, already_in_path, and message. For Fish, expect stable output even if setup rewrites the generated file. |
| Did the current shell cache an old location? | hash -r, then command -v mars | The path changes to the intended binary, or remains correct. |
| Can completions be generated? | mars completion zsh --help | Shell-specific installation help and the --no-descriptions flag. |
Recipes
New source checkout
git clone https://github.com/greaveselliott/MARS.git
cd MARS
make install
mars setup
mars doctorOrdinary setup requires no GitHub credential; authenticated release access remains optional.
Fix command not found after install
cd /path/to/MARS
make install
mars path setup
exec "$SHELL" -l
mars versionOpening a fresh login shell is often cleaner than trying to source every possible profile manually.
Find duplicate binaries
command -v mars
which -a mars
mars versionIf multiple paths appear, remove or demote the older path before retrying the update.
Install Fish completion locally
mkdir -p ~/.config/fish/completions
mars completion fish > ~/.config/fish/completions/mars.fish
exec fishFish PATH setup and Fish completion use different files: conf.d/mars.fish for PATH and completions/mars.fish for completion.
Troubleshooting
| Symptom | Likely cause | Recovery |
|---|---|---|
mars is not found |
The install directory is not in this shell's PATH, or the profile change has not been loaded. | Run mars path setup from a known binary, rerun make install, then open a new terminal. |
mars version shows an older build |
A shell command cache or earlier PATH entry points at an older binary. | Run hash -r, inspect which -a mars, and remove or reorder the older path. |
mars path setup reports unsupported shell |
The detected $SHELL is not Fish, Zsh, Bash, POSIX sh family, Csh, or Tcsh. |
Pass --shell zsh or add the reported install directory to PATH manually. |
| Dry run says current PATH is already correct | The running shell can find the directory, but future shells may still need a profile snippet. | Apply mars path setup when you want future shells configured. For Fish, repeated setup can rewrite the generated file without adding duplicate PATH entries. |
| Bash completion does not load | The bash-completion package is missing or the system completion directory is not sourced. |
Install bash-completion, then follow mars completion bash --help. |
| Zsh completion does not load | compinit is not enabled or the generated _mars file is outside fpath. |
Enable autoload -U compinit; compinit, install into an fpath directory, and start a new shell. |
| Permission denied writing completion script | The persistent completion directory is system-owned. | Choose a user-owned completion directory, or use the package manager's recommended privileged install path intentionally. |
| PowerShell completion only works once | The current-session command was run, but profile persistence was not configured. | Add the output of mars completion powershell to the PowerShell profile. |
For broader first-run, model, dashboard, target harness, release, and DocSync failures, open the Troubleshooting Guide.