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

```sh
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:

```sh
cargo --version
rustc --version
rustfmt --version
```

On Ubuntu or WSL, provider dependencies may also need:

```sh
sudo apt update
sudo apt install pkg-config libssl-dev
```

## Configure a Provider

For OpenAI-compatible hosted providers, set an API key:

```sh
export OPENAI_API_KEY="..."
```

For a local OpenAI-compatible provider, create a config file:

```toml
[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.

## Configure Command Risk Rules

Exoshell ships with conservative default rules for obvious risky command suggestions. You can add your own rules at runtime:

```toml
[commands.risk]
include_defaults = true

[[commands.risk.rules]]
match_all = ["kubectl delete", "--all"]
reason = "cluster-wide deletion"
shell = "posix"

[[commands.risk.rules]]
match_all = ["terraform apply"]
reason = "infrastructure mutation"
shell = "posix"
```

`match_all` is a list of case-insensitive substrings that must all appear in the suggested command. `shell` is optional; use `posix` or `powershell`.

To replace the built-in defaults entirely:

```toml
[commands.risk]
include_defaults = false
```

## Start Exoshell

Run with defaults:

```sh
cargo run
```

Run with a config file:

```sh
cargo run -- --config path/to/config.toml
```

Select a shell family:

```sh
cargo run -- --shell posix
cargo run -- --shell powershell
```

Select an operating stance:

```sh
cargo run -- --stance audit
```

## First Session

At the prompt:

```text
exo> /help
```

Attach a note as explicit context:

```text
exo> /add-note this repo is a Rust CLI called Exoshell
```

Inspect context:

```text
exo> /context
exo> /context stats
```

Ask a question:

```text
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:

```text
exo> /add-file Cargo.toml
```

Add a shallow directory summary:

```text
exo> /add-dir src
```

Paste command output without Exoshell running the command:

```text
exo> /add-output
paste command output; finish with a single '.' line
... test result: ok
... .
```

Inspect one entry:

```text
exo> /context show ctx-001
```

Control inclusion:

```text
exo> /context disable ctx-001
exo> /context enable ctx-001
```

Control pruning preference:

```text
exo> /context pin ctx-001
exo> /context priority ctx-001 high
```

Remove an entry:

```text
exo> /context remove ctx-001
```

## Stance Tour

Stances change the compact behavior fragment in the prompt.

Show the current stance:

```text
exo> /stance
```

Switch stance:

```text
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:

```text
exo> /copy cmd-001
```

Clipboard support is not implemented yet, so `/copy` prints the command. It does not execute it.

Explain a suggestion:

```text
exo> /explain cmd-001
```

Discard a suggestion:

```text
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:

```text
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:

```text
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:

```sh
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:

```sh
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:

```sh
sudo apt install pkg-config libssl-dev
```

## Exit

Quit the REPL:

```text
exo> /exit
```

If transcripts are enabled, Exoshell writes a markdown transcript at shutdown.