@intent-systems/nexus 2026.1.5-4 → 2026.1.5-8

package/skills/guides/onboarding/docs/canonical/02_CLI_REFERENCE.md

@@ -0,0 +1,404 @@
+# Nexus CLI Reference
+
+> Complete command documentation.
+
+---
+
+## Philosophy
+
+The `nexus` CLI is a **discovery and guidance system**. It helps agents:
+
+1. Orient themselves (`nexus status`)
+2. Discover capabilities (`nexus capabilities`)
+3. Access skill guides (`nexus skill use`)
+4. Manage credentials (`nexus credential`)
+
+**It does NOT wrap tool execution.** After reading a skill guide, agents use tools directly.
+
+---
+
+## Command Tree
+
+```bash
+nexus
+├── status                      # Main entry point - orientation
+├── capabilities                # Full capability map
+├── identity                    # Show identity file paths
+│
+├── skill
+│   ├── use <name>              # Get skill guide (SKILL.md)
+│   ├── info <name>             # Skill metadata and status
+│   └── list [--type] [--status]# List available skills
+│
+├── credential
+│   ├── list                    # List all credentials
+│   ├── add                     # Add new credential
+│   ├── get <service/account>   # Retrieve credential value
+│   ├── verify <service>        # Test credential works
+│   ├── remove <service/account># Remove credential
+│   └── scan [--deep]           # Detect from environment
+│
+├── config
+│   ├── list                    # Show all config
+│   ├── get <key>               # Get config value
+│   └── set <key> <value>       # Set config value
+│
+└── init [path]                 # Create new workspace
+```
+
+---
+
+## Orientation Commands
+
+### `nexus status`
+
+Main entry point for agents. Shows current state, capabilities, and suggestions.
+
+```bash
+nexus status [options]
+
+Options:
+  --json          Output as JSON
+  --brief         Compact output
+```
+
+**Output:**
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║                        Nexus Status                            ║
+║                        darwin/arm64                            ║
+╚════════════════════════════════════════════════════════════════╝
+
+👤 Identity
+   User: Tyler
+         → state/user/IDENTITY.md
+   
+   Agent: Echo
+         → state/agents/echo/IDENTITY.md
+         → state/agents/echo/SOUL.md
+
+🔑 Credentials (12 configured)
+   ✅ anthropic, openai, gemini
+   ✅ google-oauth, github, discord
+   ❌ twitter - broken
+
+🎯 Capabilities (18/58 active)
+   ✅ email-read, email-send
+   ✅ messaging-read
+   ⭐ chat-read, chat-send (ready, unused)
+
+📊 Most used: gog (47), eve (23)
+
+🎯 Suggestions
+   1. Try Discord - configured but never used
+   2. Fix twitter credentials
+```
+
+**Bootstrap detection:** If identity files don't exist, shows bootstrap instructions instead.
+
+### `nexus capabilities`
+
+Full capability map showing everything possible.
+
+```bash
+nexus capabilities [options]
+
+Options:
+  --json              Output as JSON
+  --category <name>   Filter by category
+  --status <status>   Filter by status
+```
+
+**Output:**
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║                     Nexus Capabilities                         ║
+╚════════════════════════════════════════════════════════════════╝
+
+Legend: ✅ active  ⭐ ready  🔧 needs-setup  📥 needs-install  ⛔ unavailable
+
+🗣️ Communication (7/8)
+   ✅ email-read ─────── gog + google-oauth
+   ✅ email-send ─────── gog + google-oauth
+   ✅ messaging-read ─── eve, imsg
+   ⭐ chat-read ──────── discord (ready)
+
+📱 Social & News (2/5)
+   ✅ social-x ───────── bird + twitter
+   🔧 news ───────────── brave-search (needs API key)
+
+...
+
+Summary: 18 active │ 8 ready │ 5 needs-setup
+```
+
+### `nexus identity`
+
+Show paths to identity documents.
+
+```bash
+nexus identity [user|agent]
+
+Options:
+  --json          Output as JSON
+```
+
+**Output:**
+
+```
+👤 User Identity
+   → state/user/IDENTITY.md
+
+🤖 Agent Identity (Echo)
+   → state/agents/echo/IDENTITY.md
+   → state/agents/echo/SOUL.md
+   → state/agents/echo/MEMORY.md
+```
+
+---
+
+## Skill Commands
+
+### `nexus skill use <name>`
+
+**Primary command.** Returns the SKILL.md guide for any skill.
+
+```bash
+nexus skill use <name>
+```
+
+**Behavior:**
+- Looks up skill in `skills/tools/`, `skills/connectors/`, or `skills/guides/`
+- Returns the full SKILL.md content
+- Logs usage to `state/skills/{name}/usage.log`
+
+**Output:** The skill's SKILL.md content, ready for the agent to read and act on.
+
+### `nexus skill info <name>`
+
+Show metadata, status, and usage statistics.
+
+```bash
+nexus skill info <name> [options]
+
+Options:
+  --json          Output as JSON
+```
+
+**Output:**
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║                           gog                                  ║
+╚════════════════════════════════════════════════════════════════╝
+
+Type: tool
+Status: ✅ active
+Description: Google Workspace CLI for Gmail, Calendar, Drive
+
+Provides: email-read, email-send, calendar, cloud-storage, contacts
+Requires:
+  - Connector: google-oauth
+  - Binary: gog
+
+Usage:
+  Times used: 47
+  Last used: 2 hours ago
+
+Location: skills/tools/gog/SKILL.md
+```
+
+### `nexus skill list`
+
+List available skills.
+
+```bash
+nexus skill list [options]
+
+Options:
+  --type <type>       Filter by type (tool|connector|guide)
+  --status <status>   Filter by status (active|ready|needs-setup|needs-install)
+  --json              Output as JSON
+```
+
+**Output:**
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║                        Nexus Skills                            ║
+╚════════════════════════════════════════════════════════════════╝
+
+🔧 Tools (14)
+   ✅ gog          email, calendar, drive
+   ✅ eve          messaging, insights
+   ⭐ aix          session analytics
+   📥 ffmpeg       video processing
+
+🔌 Connectors (11)
+   ✅ google-oauth google services auth
+   ✅ anthropic    claude models
+   🔧 brave-search web search (needs API key)
+
+📖 Guides (8)
+   ✅ computer-use browser automation
+   ✅ filesystem   file organization
+
+Legend: ✅ active  ⭐ ready  🔧 needs-setup  📥 needs-install
+```
+
+---
+
+## Credential Commands
+
+### `nexus credential list`
+
+List all configured credentials.
+
+```bash
+nexus credential list [options]
+
+Options:
+  --service <name>    Filter by service
+  --broken            Only show broken credentials
+  --json              Output as JSON
+```
+
+### `nexus credential add`
+
+Add a new credential. Interactive or flag-based.
+
+```bash
+# Interactive
+nexus credential add
+
+# Non-interactive
+nexus credential add \
+  --service anthropic \
+  --account tyler@anthropic.com \
+  --type api-key \
+  --storage keychain \
+  --value "sk-ant-xxxxx"
+```
+
+**Flags:**
+- `--service` - Service name
+- `--account` - Account identifier (email/username)
+- `--type` - Credential type (api-key, oauth, token)
+- `--storage` - Storage provider (keychain, 1password, env)
+- `--value` - Secret value (for keychain storage)
+
+### `nexus credential get <service/account>`
+
+Retrieve a credential value for scripts/agents.
+
+```bash
+nexus credential get anthropic/tyler@anthropic.com
+# Output: sk-ant-xxxxx (just the value)
+```
+
+### `nexus credential verify <service>`
+
+Test that credentials work.
+
+```bash
+nexus credential verify google-oauth
+```
+
+### `nexus credential scan`
+
+Detect credentials from environment variables.
+
+```bash
+nexus credential scan              # Known variables only
+nexus credential scan --deep       # All env vars (pattern matching)
+nexus credential scan --import     # Import found credentials
+```
+
+---
+
+## Config Commands
+
+### `nexus config list|get|set`
+
+Manage workspace configuration.
+
+```bash
+nexus config list
+nexus config get credential-store
+nexus config set credential-store keychain
+```
+
+---
+
+## Workspace Commands
+
+### `nexus init`
+
+Create a new nexus workspace.
+
+```bash
+nexus init              # Create at ~/nexus
+nexus init /path/to    # Create at specific path
+```
+
+**Creates:**
+- Folder structure (`skills/`, `state/`, `home/`)
+- Root `AGENTS.md`
+- `.cursor/rules`
+- `.cursor/hooks.json`
+- `.cursor/hooks/nexus-session-start.js`
+- Empty identity templates
+
+---
+
+## Status Levels
+
+| Emoji | Status | Meaning |
+|-------|--------|---------|
+| ✅ | `active` | Configured AND has been used |
+| ⭐ | `ready` | Configured, never used |
+| 🔧 | `needs-setup` | Installed but needs credentials |
+| 📥 | `needs-install` | Binary not installed |
+| ⛔ | `unavailable` | Not available on this platform |
+| ❌ | `broken` | Was working, now failing |
+
+---
+
+## JSON Output
+
+All commands support `--json` for programmatic use:
+
+```bash
+nexus status --json
+nexus capabilities --json
+nexus skill list --json
+nexus skill info gog --json
+```
+
+---
+
+## Agent Workflow
+
+Typical agent session:
+
+```bash
+# 1. Orient (hooks may do this automatically)
+nexus status
+
+# 2. Read identity files (paths from status)
+# (agent reads directly)
+
+# 3. Need to use a capability? Get the skill guide
+nexus skill use gog
+
+# 4. Follow the guide, use the tool directly
+gog gmail search "is:unread"
+
+# 5. If credentials fail
+nexus credential verify google-oauth
+
+# 6. Grow capabilities
+nexus capabilities --status needs-setup
+```