Running Shelly

Running Shelly

Install or build

cargo install shelly-shell

For a checkout, use a Rust toolchain supporting edition 2024:

cargo build --locked
./target/debug/shelly

The executable contains its own standard library. You can select another library through startup settings.

Execution modes

Form	Purpose
shelly	Start the REPL when connected to a terminal; otherwise read stdin
shelly file.shy one two	Run a file; $args contains one and two
shelly -c 'echo $args...' one two	Execute command-line source
shelly -s one two	Read source from stdin, with script arguments
shelly -i	Force interactive mode
shelly --language-server	Serve editor requests over stdio

Shell flags precede the script filename. Arguments after it belong to the script. Use shelly --help for the installed build's complete option list.

Useful options include --login/-l, --norc, --rcfile PATH, --no-banner/-b, --mono/-m, and --tab-width NUMBER/-t. Tab widths accept 1 through 32; a file header #tab-size N overrides the CLI setting, which overrides $SHELLY_TAB_SIZE (default 4). See pipeline splits. The RC loads only in interactive mode. Login profiles are a separate startup step.

Script arguments

fn announce($name: String): String { "Welcome, " + $name }
echo (announce "traveler")

Welcome, traveler

In a real script, replace the literal with $args[0] after checking $args.count. $args... expands all supplied arguments. Scripts do not automatically print expression results.

A script may start with #!/usr/bin/env shelly. Make it executable to invoke it as a program. This is separate from Shelly's checked backtick references.

Login shells

On Unix systems the shell must be installed at a stable absolute path. macOS and other systems that check /etc/shells need that path registered before chsh can select it. For a Cargo installation the path is normally $HOME/.cargo/bin/shelly. Keep another working terminal available while changing login-shell settings. See Startup and standard library for profile order.

Development builds

Use a separate directory when validating release code while an installed release is your login shell:

cargo build --locked --release --target-dir target/test-validation
./target/test-validation/release/shelly -m test.shy

Rebuilding a binary does not replace the program already running in an open session. Start a new Shelly process to use a newer parser and runtime.

---

Related: REPL and history · Startup