# The `strand` command

Everything `strand` does is one of its commands: `strand <command> [args]`. This page is made from what the binary prints for `strand --help` and for each command's own `--help`, and the site's build checks it against the binary, so it lists exactly the commands and flags `strand` has.

## Commands

| Command | What it does |
| --- | --- |
| [`strand run`](#strand-run) | run the config \[dir\] (default $XDG\_CONFIG\_HOME/strand; --demo: the M0 hello bar) |
| [`strand check`](#strand-check) | check the config without running it \[dir \| file\] |
| [`strand fmt`](#strand-fmt) | format .strand files in place \[--check\] \[paths\] |
| [`strand watch`](#strand-watch) | stream reload events, faults and notices (--json) |
| [`strand reload`](#strand-reload) | rescan now (--hard drops non-persisted state) |
| [`strand get`](#strand-get) | read an exported value, a settings field or a token ('$accent') (--json) |
| [`strand set`](#strand-set) | write an exported value, a settings field or an rw service field (strand set theme.look mocha; audio.sink.volume \+5%; '$accent' overlays a token) |
| [`strand toggle`](#strand-toggle) | flip an exported boolean |
| [`strand call`](#strand-call) | invoke a service action (strand call notifications.clear) (--json) |
| [`strand clear`](#strand-clear) | drop a runtime overlay (strand clear '$accent') |
| [`strand new`](#strand-new) | write a starter shell into \[dir\] (default $XDG\_CONFIG\_HOME/strand; refuses a non-empty dir) |
| [`strand export`](#strand-export) | write the palette: json \| base24 \| --template \<file\> \[--palette \<expr\>\] \[-o \<file\>\] |
| [`strand compositor-rules`](#strand-compositor-rules) | print blur rules for the compositor |
| [`strand report`](#strand-report) | dump compositor, protocols, scales, memory, GPU and frame stats (--json); with words (strand report the clock jumped), save a glitch report |
| [`strand replay`](#strand-replay) | replay a glitch report \[report-dir\] (default: the newest) in the evaluation sandbox and open its viewer (--no-open); needs strand-eval next to strand |

## Options

| Option | |
| --- | --- |
| `--write-schemas` | write this plugin binary's service schemas for strand check and the LSP |
| `-V`, `--version` | print the version |

## Environment

Not passed to programs the shell starts.

| Variable | |
| --- | --- |
| `STRAND_SOCKET` | the shell's socket (default $XDG\_RUNTIME\_DIR/strand-\<display\>.sock) |
| `STRAND_STATE_DIR` | the shell's state directory (default $XDG\_STATE\_HOME/strand) |

## `strand run`

```text
usage: strand run [dir | --demo]
```

## `strand check`

```text
usage: strand check [dir | file]
```

Parses and type-checks every .strand file under the directory (default $XDG\_CONFIG\_HOME/strand) as one config and prints diagnostics; exits non-zero on errors. Given a file, checks it with the rest of its config (the default directory if the file is in it, else the file's directory) and prints the diagnostics in that file, and a missing lock helper.

## `strand fmt`

```text
usage: strand fmt [--check] [--] [dir | file]...
```

Formats .strand files in place (a directory means its .strand files, as `strand check` loads them; default $XDG\_CONFIG\_HOME/strand). With --check, writes nothing, lists the files that are not formatted and exits non-zero if there are any. Files with syntax errors are reported and left as written.

## `strand watch`

```text
usage: strand watch [--json]
```

## `strand reload`

```text
usage: strand reload [--hard]
```

## `strand get`

```text
usage: strand get [--json] <file.name | '$token'>
```

## `strand set`

```text
usage: strand set <file.name> <value>
```

## `strand toggle`

```text
usage: strand toggle <file.name>
```

## `strand call`

```text
usage: strand call [--json] <service.action> [args…]
```

## `strand clear`

```text
usage: strand clear <'$token' | file.settings.field>
```

## `strand new`

```text
usage: strand new [dir]
```

## `strand export`

```text
usage: strand export json | base24 | --template <file> [--palette '<expr>'] [-o <file>]
```

## `strand compositor-rules`

```text
usage: strand compositor-rules [dir] [--classic]
```

Prints Hyprland layer rules that blur behind the surfaces of the config at dir (default $XDG\_CONFIG\_HOME/strand) that ask for `blur`, matched by their strand-\<Name\> namespaces, for you to paste into your Hyprland config. The default is Hyprland 0.56's Lua config (hl.layer\_rule); --classic prints hyprlang `layerrule =` lines for older versions. Nothing is applied to the running session.

## `strand report`

```text
usage: strand report [--json] [what you saw…]
```

## `strand replay`

```text
usage: strand replay [report-dir] [--no-open] [--out DIR] [--to SCN] [--output NAME] [--traced SECONDS|all] [--frames all|failing|none] [--gpu]
       strand replay clip [report-dir] --from T [--to T] [--node SEL]... [--note TEXT] [--json] [--save FILE.zip]
```

Replays a glitch report (default: the newest under the state directory's reports/) in strand-eval, the evaluation sandbox, found next to strand or on PATH, which takes these options; `clip` makes a clip of the replay instead.