Agent skill
cortex
CLI for managing the Cortex email automation pipeline. Use this skill when the user wants to query emails, check queue status, trigger backfills, view classifications, or manage the email triage system. Triggers on keywords like "cortex", "email pipeline", "queue status", "classification", "backfill", "triage".
Install this agent skill to your Project
npx add-skill https://github.com/devonjones/cortex-utils/tree/main/skills/cortex
Metadata
Additional technical details for this skill
- author
- Devon Jones
- version
- 0.1.0
- repository
- https://github.com/devonjones/cortex-utils
SKILL.md
Cortex Gateway CLI
Command-line interface for managing the Cortex email automation pipeline.
Prerequisites
Note: This skill documentation lives in the cortex-utils repository but describes the cortex CLI tool provided by the separate cortex-gateway project. The gateway provides a unified REST API for Cortex services, and the CLI is the command-line interface to that API.
The cortex CLI is installed from the cortex-gateway package:
# Install from cortex-gateway repo
uv pip install git+https://github.com/devonjones/cortex-gateway.git
# Or if working locally
cd ~/Projects/cortex/gateway && uv pip install -e .
Configuration
Set the gateway URL via environment variable or CLI flag:
export CORTEX_GATEWAY_URL=http://localhost:8097 # Example
cortex --url http://custom-host:8097 <command>
Command Reference
Global Options
| Option | Description |
|---|---|
--url |
Gateway URL (env: CORTEX_GATEWAY_URL) |
-j, --json-output |
Output raw JSON instead of formatted tables |
Health Check
cortex health
Email Commands
# List emails (paginated)
cortex emails list [-n LIMIT] [--offset N] [-l LABEL_ID]
# Get email details
cortex emails get <gmail_id>
# Get email body (from DuckDB)
cortex emails body <gmail_id>
# Get plain text content
cortex emails text <gmail_id>
# Email statistics
cortex emails stats
# Emails by Gmail label ID (useful for backfill planning)
cortex emails by-label <label_id> [-n LIMIT]
# Classification breakdown for a sender (debug rules)
cortex emails sender <from_addr>
# Top labels by email count (rule coverage)
cortex emails distribution [-n LIMIT]
# Senders only in Uncategorized (missing rules)
cortex emails uncategorized [-n LIMIT]
Queue Commands
# Queue depths by status
cortex queue stats
# List failed jobs
cortex queue failed [-q QUEUE_NAME] [-n LIMIT]
# Retry a failed job
cortex queue retry <job_id>
# Delete a failed job
cortex queue delete <job_id>
# Retry all failed jobs for a queue
cortex queue retry-all <queue_name>
Backfill Commands (Re-enqueue existing emails)
# Trigger backfill to worker queue
cortex backfill trigger [-q QUEUE] [-d DAYS] [-l LABEL] [-p PRIORITY]
# Example: cortex backfill trigger -q triage -d 7 -p -100
# Check backfill status
cortex backfill status
# Cancel pending backfill jobs
cortex backfill cancel <queue_name>
Triage Commands
# Classification statistics
cortex triage stats
# Re-run triage on emails
cortex triage rerun [-i GMAIL_ID]... [-l LABEL] [-s SENDER]... [-d DAYS] [-f] [-p PRIORITY]
# -f: force rerun even if pending
# -s, --sender: filter by sender email (supports glob with *). Can be specified multiple times.
# Examples:
# cortex triage rerun -l Cortex/Uncategorized -d 30
# cortex triage rerun -s "service@paypal.com" -d 7
# cortex triage rerun -s "*@substack.com" -d 14
# cortex triage rerun -s "service@paypal.com" -s "alerts@github.com" -d 7
# List recent classifications
cortex triage list [-n LIMIT] [-l LABEL]
Sync Commands (Gmail API backfill)
# Trigger Gmail API historical sync
cortex sync backfill [-d DAYS] [-a YYYY-MM-DD]
# Example: cortex sync backfill -d 30
# List sync jobs
cortex sync jobs [-n LIMIT] [-s STATUS]
# Get specific job status
cortex sync job <job_id>
# Cancel a sync job
cortex sync cancel <job_id>
Common Workflows
Find missing rules
# Top senders without proper classification
cortex emails uncategorized -n 20
# Check how a sender's emails are classified
cortex emails sender notifications@example.com
Debug classification issues
# See all labels and their counts
cortex emails distribution -n 100
# Find emails with a specific Gmail label
cortex emails by-label Label_117 -n 50
Re-process emails
# Re-run triage on Uncategorized emails from last 7 days
cortex triage rerun -l Cortex/Uncategorized -d 7
# Re-run triage for specific sender
cortex triage rerun -s "service@paypal.com" -d 7
# Re-run triage for all senders from a domain (glob pattern)
cortex triage rerun -s "*@substack.com" -d 14
# Backfill specific emails to triage queue
cortex backfill trigger -q triage -l Label_123 -d 30
Monitor queue health
# Check all queue depths
cortex queue stats
# View failed jobs
cortex queue failed -n 20
# Retry all failed labeling jobs
cortex queue retry-all labeling
Historical sync from Gmail
# Sync last 30 days from Gmail API
cortex sync backfill -d 30
# Check sync progress
cortex sync jobs
Config Management
Triage rules configuration is managed via the Gateway REST API (not CLI).
Update Config Workflow
-
Edit the rules YAML at
~/cortex-config/rules.yamlon Hades (or locally first) -
Upload via API:
curl -X PUT http://10.5.2.21:8097/config \
-H "Content-Type: text/plain" \
-H "X-Created-By: your-name@context" \
-H "X-Notes: Description of changes" \
--data-binary @/path/to/rules.yaml
- Reload triage worker:
ssh devon@10.5.2.21 "docker kill -s SIGHUP cortex-triage-worker"
- Verify reload:
ssh devon@10.5.2.21 "docker logs cortex-triage-worker 2>&1 | grep -E 'reload|version' | tail -3"
Config API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/config |
GET | Download active config as YAML |
/config |
PUT/POST | Upload new config version |
/config/validate |
POST | Validate YAML without saving |
/config/versions |
GET | List all config versions |
/config/versions/<n> |
GET | Download specific version |
/config/rollback/<n> |
POST | Rollback to version N |
/config/diff/<v1>/<v2> |
GET | Compare two versions |
Validate Before Upload
curl -X POST http://10.5.2.21:8097/config/validate \
-H "Content-Type: text/plain" \
--data-binary @/path/to/rules.yaml
Returns {"valid": true, "stats": {...}} or {"valid": false, "errors": [...]}.
Output Formats
By default, commands output formatted tables. Use -j for JSON:
# Table format (default)
cortex emails uncategorized -n 5
# JSON format
cortex -j emails uncategorized -n 5
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
mattpocock/skills
setup-pre-commit
Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
mattpocock/skills
migrate-to-shoehorn
Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
mattpocock/skills
git-guardrails-claude-code
Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
mattpocock/skills
scaffold-exercises
Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
mattpocock/skills
edit-article
Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
mattpocock/skills
obsidian-vault
Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
Didn't find tool you were looking for?