git.iko.soy/crush
on main help sign in
docs(skill): document shell expansion in crush-config skill
06f4350Christian Rocha
internal/skills/builtin/crush-config/SKILL.md+57−2
compare with main
unifiedsplit
@@ -29,6 +29,58 @@ Crush uses JSON configuration files with the following priority (highest to lowe
29
29
30The `$schema` property enables IDE autocomplete but is optional.
30The `$schema` property enables IDE autocomplete but is optional.
31
31
32+## Shell Expansion
33+
34+Crush runs selected string fields through an embedded bash-compatible
35+shell at load time, so values can pull from env vars, files, or helper
36+commands.
37+
38+Supported constructs (match the `bash` tool):
39+
40+- `$VAR` and `${VAR}`
41+- `${VAR:-default}`, `${VAR:+alt}`, `${VAR:?message}`
42+- `$(command)` with full quoting and nesting
43+- Single- and double-quoted strings, escapes
44+
45+Default semantics match bash: an unset variable expands to an empty
46+string, no error. A failing `$(command)` is always a hard error. For
47+required credentials, use `${VAR:?message}` so a missing variable
48+fails loudly at load time with your message.
49+
50+```json
51+{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }
52+```
53+
54+### Which fields expand
55+
56+| Surface | Expansion |
57+| --------------------------------------------------- | --------- |
58+| Provider `api_key`, `base_url`, `api_endpoint` | yes |
59+| Provider `extra_headers` | yes |
60+| Provider `extra_body` | **no** |
61+| MCP `command`, `args`, `env`, `headers`, `url` | yes |
62+| LSP `command`, `args`, `env` | yes |
63+| Hook `command` | runs via `sh -c`, not the resolver |
64+
65+`extra_body` is a JSON passthrough. If you need env-driven values in
66+a request body, put them in `extra_headers`, `api_key`, or
67+`base_url` instead.
68+
69+### Empty-resolved headers are dropped
70+
71+When a header value resolves to the empty string (unset variable,
72+`$(echo)`, or literal `""`), the header is omitted from the
73+outgoing request. This keeps optional env-gated headers like
74+`"OpenAI-Organization": "$OPENAI_ORG_ID"` working cleanly when the
75+var isn't set. Applies to MCP `headers` and provider `extra_headers`.
76+
77+### Security note
78+
79+`crush.json` is trusted code. Any `$(...)` in it runs at load time
80+with the invoking user's shell privileges, before the UI appears.
81+Don't launch Crush in a directory whose `crush.json` you haven't
82+reviewed.
83+
32## Common Tasks
84## Common Tasks
33
85
34- Add a custom provider: add an entry under `providers` with `type`, `base_url`, `api_key`, and `models`.
86- Add a custom provider: add an entry under `providers` with `type`, `base_url`, `api_key`, and `models`.
@@ -79,7 +131,8 @@ The `$schema` property enables IDE autocomplete but is optional.
79```
131```
80
132
81- `type` (required): `openai`, `openai-compat`, or `anthropic`
133- `type` (required): `openai`, `openai-compat`, or `anthropic`
82−- `api_key` supports `$ENV_VAR` syntax.
134+- `api_key`, `base_url`, `api_endpoint`, and `extra_headers` are shell-expanded (see [Shell Expansion](#shell-expansion)).
135+- `extra_body` is a JSON passthrough and is **not** expanded.
83- Additional fields: `disable`, `system_prompt_prefix`, `extra_headers`, `extra_body`, `provider_options`.
136- Additional fields: `disable`, `system_prompt_prefix`, `extra_headers`, `extra_body`, `provider_options`.
84
137
85## LSP Configuration
138## LSP Configuration
@@ -89,7 +142,7 @@ The `$schema` property enables IDE autocomplete but is optional.
89 "lsp": {
142 "lsp": {
90 "go": {
143 "go": {
91 "command": "gopls",
144 "command": "gopls",
92− "env": { "GOTOOLCHAIN": "go1.24.5" }
145+ "env": { "GOPATH": "$HOME/go" }
93 },
146 },
94 "typescript": {
147 "typescript": {
95 "command": "typescript-language-server",
148 "command": "typescript-language-server",
@@ -100,6 +153,7 @@ The `$schema` property enables IDE autocomplete but is optional.
100```
153```
101
154
102- `command` (required), `args`, `env` cover most setups.
155- `command` (required), `args`, `env` cover most setups.
156+- `command`, `args`, and `env` values are shell-expanded (see [Shell Expansion](#shell-expansion)).
103- Additional fields: `disabled`, `filetypes`, `root_markers`, `init_options`, `options`, `timeout`.
157- Additional fields: `disabled`, `filetypes`, `root_markers`, `init_options`, `options`, `timeout`.
104
158
105## MCP Servers
159## MCP Servers
@@ -124,6 +178,7 @@ The `$schema` property enables IDE autocomplete but is optional.
124```
178```
125
179
126- `type` (required): `stdio`, `sse`, or `http`
180- `type` (required): `stdio`, `sse`, or `http`
181+- `command`, `args`, `env`, `headers`, and `url` are shell-expanded (see [Shell Expansion](#shell-expansion)).
127- Additional fields: `env`, `disabled`, `disabled_tools`, `timeout`.
182- Additional fields: `env`, `disabled`, `disabled_tools`, `timeout`.
128
183
129## Options
184## Options