> The Jitzu shell is a feature-rich interactive environment that blends a Unix-style command line with the full Jitzu language.

# Jitzu Shell

The Jitzu shell is a feature-rich interactive environment that blends a Unix-style command line
with the full Jitzu language. You can run shell commands, write Jitzu expressions, and pipe
between them — all in one place.

## Launching the Shell

Start the shell by running `jz` with no arguments:

```shell
jz v0.2.0

• runtime    : 10.0.0
• config     : ~/.jitzu/config.jz
• platform   : Unix

Type \`help\` to get started.

simon@dev ~/projects/api (main) *              14:23
>
```

The prompt shows your username, hostname, current directory (relative to the git root if inside a repo),
git branch with status indicators (`*` dirty, `+` staged, `?` untracked), and the current time.

Use `--no-splash` to skip the welcome banner.

## Mixing Code and Commands

The shell automatically detects whether your input is Jitzu code or a shell command.
Jitzu code is tried first; if parsing fails, the input is executed as an OS command.

### Jitzu Expressions

```jitzu
> 1 + 1
2

> let greeting = "hello from the shell"
> greeting.ToUpper()
"HELLO FROM THE SHELL"

> fun factorial(n: Int): Int {
|     if n <= 1 { 1 } else { n * factorial(n - 1) }
| }
> factorial(10)
3628800
```

### OS Commands

Commands that aren't valid Jitzu code fall through to the system shell.
Many common commands like `ls`, `grep`, and `find` are
implemented as builtins with colored output, but any program on your PATH works too:

```shell
> git log --oneline -3
a1b2c3d Add pattern matching support
b2c3d4e Fix lexer edge case
c3d4e5f Initial commit

> dotnet build
Build succeeded.
```

## Command Substitution

Use `$(command)` to capture the output of a command and insert it inline.
Nesting is supported.

```shell
> echo "I am in $(pwd)"
I am in /home/simon/projects/api

> echo "Branch: $(git branch --show-current)"
Branch: main
```

## Environment Variables

Shell-style variable expansion works with `$VAR` and `\${VAR}` syntax.
Use `export` to set and `unset` to remove environment variables.

```shell
> export EDITOR=nvim
> echo $EDITOR
nvim

> echo \${HOME}
/home/simon
```

Single-quoted strings suppress expansion: `echo '$HOME'` prints the literal text `$HOME`.

## Multi-line Input

When a line ends with an unclosed brace, the shell continues reading on the next line
with a `|` continuation prompt:

```jitzu
> let person = {
|   name = "Alice",
|   age = 30,
|   address = {
|     city = "New York",
|     zip = "10001"
|   }
| }
> person.address.city
"New York"
```

## Glob Expansion

Arguments containing `*` or `?` are
expanded to matching file paths. Recursive `**` patterns are also supported.

```shell
> ls *.cs
Program.cs  Lexer.cs  Parser.cs

> find src/**/*.cs
src/Core/Compiler.cs
src/Core/Interpreter.cs
src/Runtime/Stack.cs
```

## Sourcing Scripts

The `source` command (or its shorthand `.`) executes a `.jz` file
line-by-line in the current session, so any variables or functions it defines remain available:

```shell
> source ~/scripts/helpers.jz
> my_helper_function("test")
"processed: test"
```

## Introspection

The shell includes commands to inspect the current session state:

- `vars` — list all defined variables and their types
- `types` — show available types (built-in, user-defined, imported)
- `functions` — show defined functions
- `reset` — clear all session state and start fresh

## Error Handling

Errors are displayed gracefully without crashing the shell. The prompt arrow turns red after a failed command:

```jitzu
> 10 / 0
Error: Division by zero

> cd nonexistent
No such directory: nonexistent
  Did you mean src/?
```