Skip to content

QUICKSTART-USER.adoc

Latest commit

 

History

History
139 lines (105 loc) · 4.03 KB

QUICKSTART-USER.adoc

File metadata and controls

139 lines (105 loc) · 4.03 KB
Raw

valence-shell — Quick Start for Users

Table of Contents

What is valence-shell?

Valence Shell (vsh) is a formally verified, reversible Unix-style shell: its core filesystem operations are backed by machine-checked proofs, and it provides a proven undo/redo layer, named checkpoints, and proof-annotated dry runs. See README.adoc for the full overview.

Important

v0.9.0 is an advanced research prototype — NOT production-ready. Great for learning and experimentation; do not use it as your login shell or trust it with irreplaceable data.

Prerequisites

The six proof systems (Coq, Lean 4, Agda, Isabelle, Mizar, Z3) are optional — they are only needed to re-check the formal proofs, not to build or run the shell.

Launch it (fastest path)

git clone https://github.com/hyperpolymath/valence-shell.git
cd valence-shell

just run          # build (debug) and start the interactive shell
# or, equivalently:
just launch

just run passes any extra arguments through to the binary:

just run --version        # print version and exit
just run path/to/script   # execute a script non-interactively

Expected first-run output is the vsh banner followed by an interactive prompt. Type help for commands, undo to reverse the last operation, and exit to leave.

Build / install

just build-cli     # release build -> impl/rust-cli/target/release/vsh
just install-cli   # cargo install to ~/.cargo/bin (then just run `vsh`)
just test-cli      # run the CLI test suite

After just install-cli, the vsh binary is on your PATH:

vsh --version
vsh                # start the shell

You can also drive Cargo directly if you prefer:

cd impl/rust-cli
cargo run                       # start the interactive shell
cargo build --release           # build the release binary
./target/release/vsh --version

Desktop integration (optional)

launch.sh is the standard-conformant launcher (E-Grade Launcher Standard). It adds a desktop menu entry so you can start vsh from your application launcher:

./launch.sh --integ      # install a desktop entry (Linux; idempotent)
./launch.sh --status     # show binary, version, platform
./launch.sh --disinteg   # remove it again (keeps your config and logs)

./launch.sh with no arguments launches the shell (same as just run). See docs/LAUNCHER.md for the full mode set and conformance notes.

Run in a container

just container-build    # build the container image (uses Containerfile)
just container-run      # run verification in the container
just container-shell    # interactive shell inside the container

Self-diagnostic

just doctor    # check required tools, hardcoded paths, environment
just heal      # attempt automatic repair (permissions, stale caches)

Get help

Uninstall

If you installed with just install-cli (which uses cargo install):

cargo uninstall vsh

A source checkout leaves nothing outside the repository directory — delete the clone to remove it. Build artifacts can be cleared with just clean.

Next steps

  • README — full feature overview and verification status

  • EXPLAINME — architecture and the claims-vs-evidence trail

  • User Guide — detailed usage

  • FAQ — common questions