4.4 KiB
Quickstart
This guide gets Exoshell running and shows the main Phase 2 workflow.
Exoshell suggests commands and explains system work. It does not execute commands.
Prerequisites
Install a current Rust toolchain with rustup.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh
sh /tmp/rustup-init.sh -y --profile default --default-toolchain stable
. "$HOME/.cargo/env"
Check the toolchain:
cargo --version
rustc --version
rustfmt --version
On Ubuntu or WSL, provider dependencies may also need:
sudo apt update
sudo apt install pkg-config libssl-dev
Configure a Provider
For OpenAI-compatible hosted providers, set an API key:
export OPENAI_API_KEY="..."
For a local OpenAI-compatible provider, create a config file:
[provider]
base_url = "http://localhost:11434/v1"
model = "local-model"
request_timeout_seconds = 120
[shell]
family = "posix"
[interaction]
stance = "operator"
Local provider URLs such as localhost and 127.0.0.1 do not require an API key.
Start Exoshell
Run with defaults:
cargo run
Run with a config file:
cargo run -- --config path/to/config.toml
Select a shell family:
cargo run -- --shell posix
cargo run -- --shell powershell
Select an operating stance:
cargo run -- --stance audit
First Session
At the prompt:
exo> /help
Attach a note as explicit context:
exo> /add-note this repo is a Rust CLI called Exoshell
Inspect context:
exo> /context
exo> /context stats
Ask a question:
exo> What should I inspect before changing command parsing?
Exoshell may return suggested commands in fenced shell blocks. Suggested commands are reviewable text. You decide whether to copy and run them in your shell.
Context Tour
Context is explicit and session-scoped. Exoshell only sends enabled context to the model.
Add a file:
exo> /add-file Cargo.toml
Add a shallow directory summary:
exo> /add-dir src
Paste command output without Exoshell running the command:
exo> /add-output
paste command output; finish with a single '.' line
... test result: ok
... .
Inspect one entry:
exo> /context show ctx-001
Control inclusion:
exo> /context disable ctx-001
exo> /context enable ctx-001
Control pruning preference:
exo> /context pin ctx-001
exo> /context priority ctx-001 high
Remove an entry:
exo> /context remove ctx-001
Stance Tour
Stances change the compact behavior fragment in the prompt.
Show the current stance:
exo> /stance
Switch stance:
exo> /stance operator
exo> /stance audit
exo> /stance teach
exo> /stance quiet
Use operator for concise next steps, audit for risk review, teach for fuller explanations, and quiet for minimal prose.
Command Suggestion Tour
When a model response includes shell fenced blocks, Exoshell assigns command IDs such as cmd-001.
Print a suggested command:
exo> /copy cmd-001
Clipboard support is not implemented yet, so /copy prints the command. It does not execute it.
Explain a suggestion:
exo> /explain cmd-001
Discard a suggestion:
exo> /discard cmd-001
Risk warnings are heuristic. Treat a warning as a prompt for careful review. Lack of a warning does not prove a command is safe.
Session Panel
Show the current operating state:
exo> /panel
The panel includes stance, shell family, provider/model, transcript state, context entries, and prompt estimates.
Multi-Line Prompts
Use /multi for longer prompts:
exo> /multi
multi-line input; finish with a single '.' line
... Review this plan:
... 1. Add parser tests.
... 2. Refactor command rendering.
... .
Piped Input
Pipe text into Exoshell as explicit context:
printf 'build failed in openssl-sys\n' | cargo run
Exoshell records piped content as user-provided context. It does not claim to know the upstream command unless you provide that separately.
Quality Checks
Run:
cargo fmt --check
cargo test
cargo clippy --all-targets --all-features
If cargo test fails on Ubuntu or WSL with an OpenSSL or pkg-config error, install:
sudo apt install pkg-config libssl-dev
Exit
Quit the REPL:
exo> /exit
If transcripts are enabled, Exoshell writes a markdown transcript at shutdown.