> ## Documentation Index > Fetch the complete documentation index at: https://workscribe.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Commands > Full reference for all Workscribe CLI commands. # Commands ## workscribe init Set up Workscribe and install or update shell hooks. ```bash theme={null} workscribe init ``` Safe to re-run at any time — installs missing hooks, updates outdated ones, and skips everything already up to date. **What it does:** * Creates `~/.workscribe/` with owner-only permissions * Initialises the SQLite database * Installs or updates the shell hook in `~/.zshrc` or `~/.bashrc` * Detects installed AI coding tools (Claude Code, Aider, etc.) and offers to install a session capture hook for each — opt-in, defaults to no * Prompts you to choose an AI provider and enter your API key **Shell hook updates:** When a new version of Workscribe ships with an updated hook, re-running `workscribe init` detects the change and prompts you to update. Your rc file is backed up before any modification. *** ## workscribe summary Generate an AI work summary for today or a specific date. ```bash theme={null} workscribe summary workscribe summary --date 2026-05-20 workscribe summary --week workscribe summary --fresh workscribe summary --slack workscribe summary --webhook ``` | Option | Description | | - | - | | `--date ` | Summarise a specific date instead of today | | `--week` | Summarise Mon–today for the current week | | `--fresh` | Bypass cache and regenerate the summary | | `--verbose` | Show all captured events (including those not sent to AI) before generating the summary | | `--slack` | Post the summary to your configured Slack webhook | | `--webhook ` | Post the summary to a custom webhook URL | **Slack setup:** 1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch** 2. Name your app, select your workspace, and click **Create App** 3. In the left sidebar under **Features**, click **Incoming Webhooks** 4. Toggle **Activate Incoming Webhooks** to On 5. Click **Add New Webhook to Workspace**, choose a channel, and click **Allow** 6. Copy the webhook URL and configure workscribe: ```bash theme={null} workscribe config set integrations.slackWebhook https://hooks.slack.com/services/... ``` Works on all Slack plans including free. No admin role required — any workspace member can create an app. Then run `workscribe summary --slack` to post. The summary is automatically formatted for Slack — headings are bolded and bullets are converted to `•`. Your OS username is prepended to the message so recipients know who sent it in shared channels. **Output format:** ``` ## project-name (branch) — 2h 15m - Implemented auth middleware and JWT validation - Resolved failing test suite - Committed fixes and pushed to remote ``` Each session gets its own heading. The heading is always generated from your captured data — project name, branch, and duration — not from the AI. **Caching:** * Daily summaries are cached per session in the database * Cached summaries are preserved when new events arrive — only new or unsummarised sessions call the AI * Weekly summaries are cached in `~/.workscribe/weekly-cache/.md` * Use `--fresh` to force regeneration of all sessions for the day *** ## workscribe week Generate an AI weekly digest covering Monday through today. ```bash theme={null} workscribe week workscribe week --fresh workscribe week --slack workscribe week --webhook ``` | Option | Description | | - | - | | `--fresh` | Bypass cache and regenerate the digest | | `--slack` | Post the digest to your configured Slack webhook | | `--webhook ` | Post the digest to a custom webhook URL | The natural pre-standup ritual for Monday morning or end-of-week reporting. Output is markdown grouped by day, with each session summarised under its project and branch. **Caching:** Results are cached in `~/.workscribe/weekly-cache/.md`. Running `workscribe week` a second time in the same week returns the cached digest instantly. Use `--fresh` to force regeneration. **Slack:** Configure your webhook first: ```bash theme={null} workscribe config set integrations.slackWebhook https://hooks.slack.com/services/... ``` Then run `workscribe week --slack` to post. See [workscribe summary](#workscribe-summary) for full Slack setup instructions. *** ## workscribe sessions List detected work sessions for a date. ```bash theme={null} workscribe sessions workscribe sessions --date 2026-05-20 ``` | Option | Description | | - | - | | `--date ` | Show sessions for a specific date | Sessions are computed by grouping events with idle gaps greater than `session.idleTimeout` (default 30 minutes) and splitting across different repositories. *** ## workscribe events List raw captured events for a date. ```bash theme={null} workscribe events workscribe events --date 2026-05-20 workscribe events --limit 20 ``` | Option | Description | | - | - | | `--date ` | Show events for a specific date | | `--limit ` | Limit the number of events shown | Events are colour-coded by category: | Category | Colour | Examples | | - | - | - | | `code_commit`, `code_push`, `code_merge` | green | `git commit`, `git push` | | `code_pull`, `branch_switch`, `code_stash` | blue | `git pull`, `git checkout` | | `test_run` | magenta | `npm test`, `npx vitest`, `pytest` | | `build` | cyan | `npm run build`, `npx tsc`, `cargo build` | | `dependency_install`, `dependency_remove`, `file_ops` | yellow | `npm install`, `rm`, `mkdir` | | `lint_run` | yellow | `npx eslint`, `npx prettier` | | `server_run` | cyan | `npm run dev`, `yarn start` | | `infrastructure` | red | `kubectl`, `docker`, `terraform` | | `script_run` | white | `npx husky`, `bash deploy.sh` | | `ai_session` | bold magenta | Claude Code, Cursor, Copilot | | `code_search`, `code_read` | dim | `grep`, `cat`, `find` | | `environment`, `git_other`, `other` | gray | `export`, `git status` | *** ## workscribe note Attach a free-text annotation to the current session. ```bash theme={null} workscribe note "Fixed race condition in auth middleware" workscribe note "Blocked by infra outage — picked up again after lunch" ``` The note is stored as an event in the database, timestamped now, and associated with the current git repo and branch. It groups into whatever session covers its timestamp when sessions are rebuilt. **Where notes appear:** * `workscribe sessions` — displayed indented under the matching session * `workscribe summary` and `workscribe week` — injected into the AI prompt before the event list so the model reads your context first, and uses it to explain the why behind the work **Removing a note:** Notes are events. Use `workscribe undo` to remove the most recently added note. *** ## workscribe undo Remove the last N captured events. ```bash theme={null} workscribe undo workscribe undo -n 5 workscribe undo --dry-run workscribe undo -n 3 --dry-run ``` | Option | Description | | - | - | | `-n, --count ` | Number of events to remove (default: 1) | | `--dry-run` | Preview what would be deleted without deleting | **Notes:** * Removes events from the database only — does not modify any exported markdown files * Automatically invalidates sessions for affected dates so they rebuild on next access * Running undo twice is safe — the second call removes the next N events *** ## workscribe clear Delete all captured events for a date. ```bash theme={null} workscribe clear workscribe clear --date 2026-05-20 workscribe clear --dry-run workscribe clear --yes ``` | Option | Description | | - | - | | `--date ` | Date to clear (default: today) | | `--dry-run` | Preview what would be deleted without deleting | | `--yes` | Skip the confirmation prompt | **Notes:** * Shows a category summary before asking for confirmation * Automatically invalidates cached sessions for the date * Use `--dry-run` to see what would be removed before committing *** ## workscribe export Generate a summary and save it as a markdown file. ```bash theme={null} workscribe export workscribe export --date 2026-05-20 workscribe export --output ~/Desktop/standup.md ``` | Option | Description | | - | - | | `--date ` | Export a specific date | | `--output ` | Custom output path (default: `~/.workscribe/exports/workscribe-.md`) | *** ## workscribe context Surface the last session for the current repo — at the moment you need it, not at end of day. ```bash theme={null} workscribe context workscribe context --file src/auth.ts workscribe context --file src/auth.ts --json ``` | Option | Description | | - | - | | `--file ` | Show the last session that touched this file (requires IDE integration) | | `--json` | Output structured JSON instead of formatted text — `null` when no session is found | **Without `--file`:** shows the most recent session for the current git repo — date, duration, branch, event count, and the AI-generated summary if one exists. **With `--file`:** narrows to the most recent session that included a `code_edit` event for that path. This is what powers the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=workscribe.workscribe)'s status bar "last worked on" indicator — surfacing "3 days ago" when you switch to a file you haven't touched recently. Neovim and other editor integrations aren't built yet. **If no summary exists** for the session, the default text output includes the command to generate one: ``` No summary — run: workscribe summary 2026-08-25 ``` **`--json` output shape**, intended for IDE integrations that need to render this themselves rather than parse formatted text: ```json theme={null} { "date": "2026-08-20", "startedAt": "2026-08-20T10:00:00.000Z", "endedAt": "2026-08-20T12:14:00.000Z", "timeAgo": "3 days ago", "durationMinutes": 134, "branch": "feature/auth", "eventCount": 42, "summary": "Implemented authentication middleware." // or null if no summary has been generated yet } ``` Prints the bare JSON value `null` (not an object) when no matching session exists. *** ## workscribe status Show capture status and event counts. ```bash theme={null} workscribe status ``` **Output includes:** * Whether capture is active or paused * Number of events captured today and total * Last captured event * Configured AI provider and model * Pending security alerts count (if any) *** ## workscribe alerts Show and manage security alerts raised when Workscribe detects a possible credential in an AI tool prompt. ```bash theme={null} workscribe alerts # list all pending alerts workscribe alerts clear # dismiss all pending alerts ``` When credentials are detected in a prompt sent to an AI tool (e.g. Claude Code), Workscribe: 1. Stores the alert in the local database. 2. Writes a signal file to `~/.workscribe/alerts.pending`. 3. Displays a one-line warning before your next shell prompt. 4. Injects a `systemMessage` into Claude's context for that turn. The `clear` subcommand marks all alerts as dismissed and removes the signal file. *** ## workscribe pause / resume Pause and resume capture. ```bash theme={null} workscribe pause workscribe resume ``` When paused, the shell hook still fires but events are silently discarded. Useful when sharing your screen or running sensitive commands you don't want journaled. *** ## workscribe uninstall Remove shell hooks and optionally delete all Workscribe data. ```bash theme={null} workscribe uninstall workscribe uninstall --hooks-only ``` | Option | Description | | - | - | | `--hooks-only` | Remove shell hooks only — skip the data deletion prompt | **What it does:** * Detects and removes the Workscribe hook block from `~/.zshrc`, `~/.bashrc`, and `~/.bash_profile` * Prompts whether to delete `~/.workscribe/` (database, config, exports) — defaults to **no** * Prints the command to remove the CLI itself (`npm uninstall -g @workscribe/cli`) **After running:** The hook is removed from your rc file but remains active in your current shell session. Either restart your terminal or run: ```bash theme={null} source ~/.zshrc # or ~/.bashrc ``` **If you've already removed the binary** and still see `_workscribe_precmd` errors, remove the hook block manually: 1. Open `~/.zshrc` (or `~/.bashrc`) 2. Delete everything between `# workscribe:hook:start` and `# workscribe:hook:end` (inclusive) 3. Run `source ~/.zshrc` or restart your terminal *** ## workscribe \_capture (IDE integration) Internal command called by shell hooks and IDE plugins. Not intended for direct use. IDE integrations call this to record a file-save or debug event without going through the shell: ```bash theme={null} workscribe _capture --type code_edit --file src/auth.ts --source vscode --cwd /path/to/repo workscribe _capture --type debug_start --source neovim --cwd /path/to/repo workscribe _capture --type task_run --source vscode --cwd /path/to/repo ``` | Option | Description | | - | - | | `--cmd ` | Shell command (shell hook only) | | `--cwd ` | Working directory (required) | | `--type ` | Event type — skips normalization. One of: `code_edit`, `debug_start`, `debug_end`, `task_run` | | `--source ` | Event source identifier (e.g. `vscode`, `neovim`, `jupyter`) | | `--file ` | File path for `code_edit` events | | `--exit ` | Exit code (shell hook only) | | `--duration ` | Duration in milliseconds (shell hook only) | **Deduplication:** `code_edit` events for the same file within 30 seconds are dropped. This absorbs rapid auto-saves without creating duplicate records. *** ## workscribe config View and update configuration. ```bash theme={null} workscribe config workscribe config set workscribe config get ``` **Examples:** ```bash theme={null} workscribe config set ai.provider anthropic workscribe config set ai.apiKey sk-... workscribe config set ai.model claude-haiku-4-5-20251001 workscribe config set session.idleTimeout 20 workscribe config set redact.extra "MY_SECRET_PATTERN" workscribe config set integrations.slackWebhook https://hooks.slack.com/services/... workscribe config set projects./Users/me/sandbox/myrepo actual-repo-name ``` **Sensitive value masking:** `workscribe config get` and `workscribe config` mask API keys, tokens, and webhook URLs — showing only the first four characters and the total length: ``` sk-a******** (51 chars) ``` This confirms a value is set without exposing it in your terminal history. See [Configuration](/docs/configuration) for the full config reference. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.