command-code 0.52.5 → 1.0.0

package/dist/bundled/command-code-knowledge/reference/custom-slash-commands.md

@@ -0,0 +1,345 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/core-concepts/slash-commands/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Slash Commands
+
+Command Code includes built-in slash commands for interactive workflows, and also supports custom slash commands from markdown files.
+
+---
+
+## Built-in Slash Commands
+
+For the full list of built-in slash commands, see [Interactive Mode — Slash Commands](https://commandcode.ai/docs/reference/cli#cli-slash-commands).
+
+---
+
+## Custom Slash Commands
+
+Custom slash commands let you save frequently used prompts as markdown files. Define a command once, then run it anytime with dynamic arguments. Commands can be project-level or user-level (shared across all projects).
+
+---
+
+## Syntax
+
+```bash
+/<command-name> [arguments]
+```
+
+| **Parameter**    | **Description**                                                   |
+| ---------------- | ----------------------------------------------------------------- |
+| `<command-name>` | Name derived from the markdown filename (without `.md` extension) |
+| `[arguments]`    | Optional arguments passed to the command                          |
+
+---
+
+## Command Types
+
+There are two types of commands:
+
+### Project-Level Commands
+
+Commands saved directly in your project. When shown in `/help`, they appear with “(project)” after their description.
+
+**Location:** `.commandcode/commands/`
+
+```bash
+# Create a project-level command
+mkdir -p .commandcode/commands
+echo "Generate unit tests for this code following our testing conventions" > .commandcode/commands/test.md
+```
+
+This makes `/test` command available only within this project.
+
+### User-Level Commands
+
+Commands that are available across all your projects. In the command menu, they appear with “(user)” after their description.
+
+**Location:** `~/.commandcode/commands/`
+
+```bash
+# Create a user-level command
+mkdir -p ~/.commandcode/commands
+echo "I am currently being onboarded on this project, help me understand it." > ~/.commandcode/commands/understand.md
+```
+
+This makes `/understand` command available in all your projects.
+
+---
+
+## Namespacing
+
+Organize commands in subdirectories. The subdirectories appear in the command description but do not affect the command name.
+
+| **File Location**                             | **Command**  | **Description Shows** |
+| --------------------------------------------- | ------------ | --------------------- |
+| `.commandcode/commands/frontend/component.md` | `/component` | `(project: frontend)` |
+| `~/.commandcode/commands/git/commit.md`       | `/commit`    | `(user: git)`         |
+| `.commandcode/commands/simple.md`             | `/simple`    | `(project)`           |
+
+### Unlimited Nesting Depth
+
+You can organize commands as deeply as needed:
+
+```
+.commandcode/commands/
+├── frontend/
+│   ├── react/
+│   │   ├── hooks/
+│   │   │   └── use-auth.md      → /use-auth (project: frontend/react/hooks)
+│   │   └── components/
+│   │       └── button.md        → /button (project: frontend/react/components)
+│   └── vue/
+│       └── composable.md        → /composable (project: frontend/vue)
+├── backend/
+│   └── api/
+│       └── endpoint.md          → /endpoint (project: backend/api)
+└── simple.md                    → /simple (project)
+```
+
+	The command name comes from the filename only, not the folder path. So
+	`frontend/button.md` and `backend/button.md` both create `/button`, they
+	will conflict. Use unique filenames like `frontend-button.md` and
+	`backend-button.md` instead.
+
+---
+
+## Arguments
+
+Pass dynamic values to commands using argument placeholders.
+
+### All Arguments with `$ARGUMENTS` (or `$@`)
+
+The `$ARGUMENTS` placeholder captures all arguments as a single string. `$@` is
+a shorthand alias for the same value, and the braced forms `${ARGUMENTS}` and
+`${@}` work too:
+
+**Command definition** (`.commandcode/commands/explain.md`):
+
+```markdown
+Explain the following concept in simple terms: $ARGUMENTS
+```
+
+**Usage:**
+
+```bash
+/explain how async await works in JavaScript
+```
+
+**Result:** `$ARGUMENTS` becomes `"how async await works in JavaScript"`
+
+### Positional Arguments with `$1`, `$2`, etc.
+
+Access specific arguments using positional parameters. Arguments start at `$1` (there is no `$0`):
+
+**Command definition** (`.commandcode/commands/create-component.md`):
+
+```markdown
+Create a $1 component named $2 with the following features: $3
+```
+
+**Usage:**
+
+```bash
+/create-component React Button "onClick and disabled props"
+```
+
+**Result:**
+
+- `$1` → `"React"`
+- `$2` → `"Button"`
+- `$3` → `"onClick and disabled props"`
+
+Positional arguments also support the braced form `${1}`, `${2}`, etc. Use it
+when a placeholder sits directly next to other characters, for example
+`v${1}.0` or `${1}px`, so the parser knows where the number ends.
+
+### Default Values with `${N:-default}`
+
+Wrap a placeholder in `${...}` and add `:-default` to fall back to a default
+value when that argument is missing or empty. This is handy for optional
+arguments:
+
+**Command definition** (`.commandcode/commands/summarize.md`):
+
+```markdown
+Summarize the current state in ${1:-7} bullet points.
+```
+
+**Usage:**
+
+```bash
+/summarize        # → "Summarize the current state in 7 bullet points."
+/summarize 3      # → "Summarize the current state in 3 bullet points."
+```
+
+Defaults work with `$@`/`$ARGUMENTS` as well — `${@:-the current diff}` uses all
+arguments when provided, otherwise the literal text `the current diff`.
+
+### Argument Slices with `${@:N}` and `${@:N:L}`
+
+Select a range of positional arguments (1-indexed) and join them with spaces:
+
+- `${@:N}` — every argument from the Nth position to the end
+- `${@:N:L}` — `L` arguments starting at the Nth position
+
+**Command definition** (`.commandcode/commands/commit.md`):
+
+```markdown
+Write a commit of type "$1" with message: ${@:2}
+```
+
+**Usage:**
+
+```bash
+/commit fix resolve the flaky login test
+```
+
+**Result:**
+
+- `$1` → `"fix"`
+- `${@:2}` → `"resolve the flaky login test"`
+
+An out-of-range slice (e.g. `${@:9}` when only three arguments were passed)
+expands to an empty string.
+
+### Quoted Strings
+
+Arguments containing spaces can be wrapped in quotes:
+
+```bash
+/create-component React "Login Form" "email validation and submit handler"
+```
+
+**Result:**
+
+- `$1` → `"React"`
+- `$2` → `"Login Form"`
+- `$3` → `"email validation and submit handler"`
+
+---
+
+## Edge Cases
+
+| **Scenario**                                   | **Behavior**                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------- |
+| Missing argument (e.g., `$3` with only 2 args) | Replaced with empty string (use `${3:-default}` for a fallback) |
+| Extra arguments                                | Captured in `$ARGUMENTS`/`$@`, ignored by unused `$N`           |
+| No arguments provided                          | `$ARGUMENTS` = `""`, all `$N` = `""`                            |
+| Command without placeholders                   | Template passed through unchanged                               |
+| Missing or empty arg with `${N:-default}`      | Replaced with `default`                                         |
+| Out-of-range slice (e.g. `${@:9}`)             | Replaced with empty string                                      |
+| Slice length past the end (e.g. `${@:2:99}`)      | Clamped to the available arguments                              |
+| Unrecognized `${...}` (e.g. `${HOME}`)         | Left untouched, so shell/env-style text is preserved            |
+
+---
+
+## Examples
+
+### Test Generator Command
+
+**File:** `.commandcode/commands/test.md`
+
+```markdown
+Write $1 tests for the following code using $2.
+
+Requirements:
+
+- Cover edge cases and error scenarios
+- Add descriptive test names
+- Follow testing best practices
+```
+
+**Usage:**
+
+```bash
+/test unit Jest
+```
+
+### Documentation Command
+
+**File:** `~/.commandcode/commands/docs.md`
+
+```markdown
+Generate documentation for this $1.
+
+Include:
+
+- Description and purpose
+- Parameters/props with types
+- Usage examples
+- Return values if applicable
+```
+
+**Usage:**
+
+```bash
+/docs function
+```
+
+---
+
+## How It Works
+
+1. **Type `/`** to open the interactive command menu
+2. **Select a command** from the dropdown (e.g., `/test`)
+3. **Command is inserted** into the input field with a trailing space
+4. **Type your arguments** (e.g., `unit Jest`)
+5. **Press Enter** to execute
+6. **Placeholders are replaced** with your arguments
+7. **Processed prompt** is sent to the AI
+
+---
+
+	Custom commands cannot override built-in commands. If you create a command
+	with the same name as a built-in, the built-in takes precedence.
+
+---
+
+## Quick Reference
+
+### Placeholders
+
+| **Placeholder**     | **Description**                               | **Example Input** | **Result**        |
+| ------------------- | --------------------------------------------- | ----------------- | ----------------- |
+| `$ARGUMENTS` / `$@` | All arguments as string                       | `unit Jest async` | `unit Jest async` |
+| `$1`                | First argument                                | `unit Jest`       | `unit`            |
+| `$2`                | Second argument                               | `unit Jest`       | `Jest`            |
+| `$N`                | Nth argument                                  | —                 | —                 |
+| `${N}`              | Braced Nth argument (safe next to other text) | `unit Jest`       | `unit`            |
+| `${N:-default}`     | Nth argument, or `default` when missing/empty | `` (none)         | `default`         |
+| `${@:N}`            | Arguments from the Nth position to the end    | `a b c`           | `b c` (N=2)       |
+| `${@:N:L}`          | `L` arguments starting at the Nth position    | `a b c d`         | `b c` (N=2, L=2)  |
+
+### Command Locations
+
+| **Type**         | **Location**                      | **Description Label** |
+| ---------------- | --------------------------------- | --------------------- |
+| Project          | `.commandcode/commands/`          | `(project)`           |
+| Project (nested) | `.commandcode/commands/subdir/`   | `(project: subdir)`   |
+| User             | `~/.commandcode/commands/`        | `(user)`              |
+| User (nested)    | `~/.commandcode/commands/subdir/` | `(user: subdir)`      |
+
+---
+
+## Troubleshooting
+
+### Command not appearing in menu
+
+1. Ensure the file has `.md` extension
+2. Check file is in correct directory (`.commandcode/commands/` or `~/.commandcode/commands/`)
+3. Verify file permissions allow reading
+
+### Arguments not being replaced
+
+1. Use `$1`, `$2`, etc. for positional args (not `$0`)
+2. Use `$ARGUMENTS` (or `$@`) for all args as a string
+3. Check for typos in placeholder names (case-sensitive)
+4. For defaults and slices, keep the braces and syntax exact: `${1:-default}`,
+   `${@:2}`, `${@:2:3}`. A malformed `${...}` expression is left in the prompt
+   unchanged rather than replaced.
+
+---
+
+## Next steps
+
+- Create your first custom slash command and try it out
+- Join our [Discord community](https://commandcode.ai/discord) for feedback, requests, and support.

package/dist/bundled/command-code-knowledge/reference/headless.md

@@ -0,0 +1,234 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/core-concepts/headless/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Headless Mode
+
+Run Command Code non-interactively in scripts, CI/CD pipelines, and automation workflows. Headless mode executes a single query, outputs the response to stdout, and exits.
+
+---
+
+## Basic Usage
+
+Use the `-p` (or `--print`) flag to run in headless mode:
+
+```bash
+cmd -p "explain this file"
+```
+
+Always wrap your query in quotes. Unquoted multi-word queries cause argument parsing errors.
+
+---
+
+## Input Methods
+
+### Direct Argument
+
+Pass your query directly after the `-p` flag:
+
+```bash
+cmd -p "refactor the auth module"
+```
+
+### Piped Stdin
+
+Pipe input from another command or file:
+
+```bash
+echo "explain this error" | cmd -p
+```
+
+```bash
+cat prompt.txt | cmd -p
+```
+
+Command Code auto-detects piped input when no query argument is provided. If stdin is a TTY and no query is given, it exits with an error.
+
+---
+
+## Permissions
+
+By default, headless mode **blocks tools that modify your system** — file writes, file edits, and shell commands are denied. This keeps automated runs safe.
+
+To enable all tools, pass `--yolo`:
+
+```bash
+cmd -p "fix the lint errors" --yolo
+```
+
+> `--dangerously-skip-permissions` is also accepted as an alias.
+
+| **Tool** | **Default (no flag)** | **With `--yolo`** |
+| -------- | --------------------- | ----------------------------------------- |
+| File reads, grep, glob | Allowed | Allowed |
+| File edits and writes | Blocked | Allowed |
+| Shell commands | Blocked | Allowed |
+
+Only use `--yolo` in trusted environments. It allows Command Code to modify files and run shell commands without confirmation.
+
+---
+
+## Tool Calls
+
+Headless mode supports multi-turn tool execution. Command Code can read files, search code, and (with permissions) edit files and run commands, just like [interactive mode](https://commandcode.ai/docs/core-concepts/interactive-mode).
+
+The conversation loop runs for up to **10 turns**. If the limit is reached, a warning is printed to stderr and the partial response is returned.
+
+---
+
+## Sessions & Resuming
+
+Each headless run persists its transcript to disk, so you can chain follow-up queries that keep prior context. Headless sessions are tagged separately and stay **hidden** from the interactive `/resume` menu and from interactive `--continue` — automation never pollutes your interactive history.
+
+### Continue the most recent run
+
+`--continue` (or `-c`) resumes the most recent headless session in the current directory:
+
+```bash
+cmd -p "find the slowest test"
+cmd -p --continue "now suggest a fix"   # carries the previous turn's context
+```
+
+If no headless session exists yet, `--continue` starts a fresh one — so a `-p --continue` loop works from the first iteration.
+
+### Resume a specific session
+
+Print the session id with `--verbose` (written to **stderr**, so stdout stays clean for piping):
+
+```bash
+cmd -p --verbose "start a code review"   # stderr → session: 9f4e1c0a-...
+```
+
+Then resume that exact session by id:
+
+```bash
+cmd -p --resume 9f4e1c0a-... "continue the review"
+```
+
+A bare `--resume` with no id errors in headless mode — there is no interactive picker. Use `--continue` to pick up the latest run instead.
+
+### Open a headless session in interactive mode
+
+Pass a headless session id to plain `cmd --resume <id>` (without `-p`) to load that transcript into a full interactive session:
+
+```bash
+cmd --resume 9f4e1c0a-...
+```
+
+---
+
+## Exit Codes
+
+Use exit codes to handle results in scripts and CI/CD:
+
+| **Code** | **Meaning** | **Constant** |
+| -------- | ----------- | ------------ |
+| `0` | Success | `EXIT_SUCCESS` |
+| `1` | General error | `EXIT_ERROR` |
+| `3` | Not authenticated | `EXIT_AUTH_ERROR` |
+| `4` | Permission denied | `EXIT_PERMISSION_DENIED` |
+| `5` | Rate limit exceeded | `EXIT_RATE_LIMITED` |
+| `6` | Network failure | `EXIT_CONNECTION_ERROR` |
+| `7` | API server error (5xx) | `EXIT_SERVER_ERROR` |
+| `8` | Max turns reached before final answer | `EXIT_MAX_TURNS_REACHED` |
+| `9` | Model produced no response | `EXIT_NO_RESPONSE` |
+| `10` | Insufficient credits | `EXIT_INSUFFICIENT_CREDITS` |
+| `130` | Interrupted (SIGINT/SIGTERM) | `EXIT_INTERRUPTED` |
+
+Example usage in a script:
+
+```bash
+cmd -p "check for security issues" --yolo
+if [ $? -ne 0 ]; then
+  echo "Command Code failed"
+  exit 1
+fi
+```
+
+---
+
+## Shell Script
+
+```bash
+#!/bin/bash
+set -e
+
+# Generate docs for changed files
+CHANGED=$(git diff --name-only HEAD~1)
+echo "Document these changed files: $CHANGED" | cmd -p --skip-onboarding
+```
+
+## Piping Output
+
+Headless mode is pipe-friendly. Output goes to stdout, errors and warnings go to stderr:
+
+```bash
+# Save response to a file
+cmd -p "generate a README for this project" > README.md
+
+# Pipe to another command
+cmd -p "list all TODO comments" | grep "critical"
+
+# Use in command substitution
+SUMMARY=$(cmd -p "summarize this codebase in one paragraph")
+```
+
+---
+
+## Related Flags
+
+Flags useful for headless and automated workflows:
+
+| **Flag** | **Description** |
+| -------- | --------------- |
+| `-p, --print [query]` | Run in headless mode |
+| `-c, --continue` | Resume the most recent headless session in this directory |
+| `-r, --resume <id>` | Resume a specific headless session by id (no bare picker in print mode) |
+| `--verbose` | Print the resolved session id to stderr (for chaining `--resume`) |
+| `--max-turns <number>` | Maximum conversation turns in print mode (default: `100`, no upper bound) |
+| `-m, --model <model>` | Run on a specific model this session |
+| `--effort <level>` | Set reasoning effort (`low`, `medium`, `high`, …) |
+| `--theme <theme>` | Set the color theme (`dark` or `light`) |
+| `--config <key=value>` | Set any setting headlessly (repeatable) — see below |
+| `--yolo` | Allow file writes and shell commands |
+| `--auto-accept` | Start in auto-accept mode (alias for `--permission-mode auto-accept`) |
+| `--skip-onboarding` | Skip taste onboarding (for CI/automated runs) |
+| `-t, --trust` | Auto-trust project (skip initial permission prompt) |
+| `--plan` | Start in plan mode (read-only exploration) |
+| `--permission-mode <mode>` | Set permission mode: `standard`, `plan`, `auto-accept` |
+
+---
+
+## Configuring settings
+
+Slash commands are interactive-only, but the settings behind them are available as **flags** —
+never as a `/slash` string on the command line. The common ones have dedicated flags
+(`--model`, `--effort`, `--theme`), and `--config key=value` reaches any setting the `/config`
+UI can change:
+
+```bash
+# Set your model + reasoning effort for this run
+cmd -p "review this diff" --model claude-sonnet-4-6 --effort high
+
+# Set any setting; repeatable. Invalid keys/values exit non-zero.
+cmd --config theme=dark --config compact-mode=fast
+```
+
+`--config` is the headless equivalent of the interactive `/config` UI, so a new setting becomes
+scriptable automatically. Confirmations print to stderr, keeping `-p` stdout clean.
+
+---
+
+## Limitations
+
+| **Limitation** | **Details** |
+| -------------- | ----------- |
+| **No interactive prompts** | No keyboard shortcuts or interactive UI. Slash commands aren't typed here — use flags instead (see [Configuring settings](#configuring-settings)); session-lifecycle commands like `/clear` and `/reload` have no meaning in one-shot mode |
+| **No resume picker** | A bare `--resume` errors in print mode; resume by explicit id or use `--continue` |
+| **Stdin timeout** | Piped stdin times out after 30 seconds if no data is received |
+
+---
+
+## Next steps
+
+- See [CLI Reference](https://commandcode.ai/docs/reference/cli) for the full list of flags and commands
+- Learn about [Interactive Mode](https://commandcode.ai/docs/core-concepts/interactive-mode) for full-featured sessions
+- Join our [Discord community](https://commandcode.ai/discord) for support