# The `deft` Binary The `deft` binary is the single entry point for everything outside the TUI: running scripts, the REPL, tests, formatting, and the package manager. It compiles to one self-contained executable with no external dependencies. ## Subcommands ``` deft <script>.dft Run a script file deft repl Start the REPL deft test [files...] Run tests deft fmt [files...] Format source files deft pkg <subcommand> Package manager deft sandbox <subcmd> Manage landlock sandbox paths deft init [name] Scaffold a new Deft project deft --version deft --help ```` ## Running a Script ``` $ deft hello.dft Alice Hello, Alice! ```` With a shebang, scripts are directly executable:

#!/usr/bin/env deft
set a [os/args]
echo "Hello, $(a(1))!"

``` $ chmod +x hello.dft $ ./hello.dft Alice Hello, Alice! ```` ### Command-line arguments Arguments after the script name are available via `os/args`:

def argv [os/args]
def script-name $argv(first)
def user-args $argv(rest)

### Exit codes `os/exit $n` exits with status `$n`. Default is 0 (success).

if not([fs/exists? "config.json"]) {
    echo "missing config"
    os/exit 1
}

## Test Runner ``` $ deft test # all tests under ./test/ $ deft test test/test_sqlite.dft # one file $ deft test test/test_refs.dft test/test_lazy_seq.dft ```` Tests are organised as `defsuite` / `deftest` blocks (see Testing). Files matching `test_*.dft` are auto-discovered. The runner prints per-test pass/fail with assertion messages, then a summary. ## Formatter ``` $ deft fmt myfile.dft # in-place $ deft fmt src/ # whole directory $ deft fmt --check myfile.dft # exit 1 if not formatted ```` Standardises whitespace, indentation, and trailing newlines. Useful in pre-commit hooks and CI. ## Package Manager ``` $ deft pkg install owner/name $ deft pkg install owner/name@1.2.0 $ deft pkg uninstall owner/name $ deft pkg list $ deft pkg available $ deft pkg info owner/name $ deft pkg registry <url> # switch registry $ deft pkg registry # show current ```` See Packages for the underlying `pkg/*` stdlib functions and package manifest format. ## Sandbox `deft sandbox` manages the Landlock path lists stored in `.deft/prelude.dft` under `:sandbox {:readonly @[...] :writable @[...]}`: ``` $ deft sandbox list # show read-only and writable lists $ deft sandbox add /srv/data # add a read-only path $ deft sandbox add ~/code/tmp -w # add a writable path (-w/--writable) $ deft sandbox remove /srv/data # remove from either list ```` Paths support a leading `~` (expanded to `$HOME` when the sandbox is applied). The sandbox itself is opt-in at runtime via `DEFT_SANDBOX=1`. See Sandbox for the full documentation. ## Build Flags The binary is built with `zig build`. The key flags: | Flag | Effect | |---|---| | `-Dffi=true` | Enable the `ffi/*` namespace (load shared libs, call C functions). Off by default. | | `-Denable-tui=true` | Build the TUI host (the `retro` / `retra` binaries). On for `retro`/`retra` targets. | | `-Doptimize=ReleaseFast` | Optimised build for production. | | `-Dtarget=x86_64-linux-gnu` | Cross-compile. | ``` $ zig build deft -Doptimize=ReleaseFast $ zig build deft -Dffi=true -Doptimize=ReleaseFast $ zig build retro ```` For FFI, see FFI. ## Capabilities `[capabilities]` returns the compiled-in feature map. Use it to write portable scripts that degrade gracefully:

def caps [capabilities]
if [get $caps :ffi] {
    # call into a C library
} {
    # pure-Deft fallback
}

Common keys: `:ffi`, `:tui`, `:websockets`, `:sqlite`, `:crypto`. ## Common Patterns ### Pipe a script into stdin ```bash $ echo 'echo "hello from stdin"' | deft - hello from stdin ```` ### Run a one-liner ```bash $ deft -e 'echo "2 + 2 = $(2 + 2)"' 2 + 2 = 4 ```` ### Combine with shell pipelines ```bash $ deft script.dft | jq '.users[]' ```` ## Quick Reference | Command | Purpose | |---|---| | `deft <file>` | Run a script | | `deft -e "code"` | Run a one-liner | | `deft -` | Read script from stdin | | `deft repl` | REPL | | `deft test [files]` | Run tests | | `deft fmt [files]` | Format | | `deft pkg <subcommand>` | Package manager | | `deft sandbox <subcommand>` | Manage Landlock path lists | | `deft init [name]` | Scaffold a project | | `deft --version` | Version | | `deft --help` | Help |