---
name: nexushub-cli
description: |
  Use when user asks about the `nh` CLI command, wants to search/list projects/tasks/issues/clients/users,
  needs help with NexusHub data queries via command line, or mentions exporting/filtering NexusHub entities.
  Triggers: "nh command", "search projects", "list tasks", "CLI query", "export issues", "find clients".
  DO NOT use for: web UI, database queries, or direct API calls.
license: MIT
metadata:
  author: NexusHub Team
  version: 1.0.0
  cli_version: 1.0.0
  supported_entities: [projects, tasks, issues, clients, users]
user-invocable: true
allowed-tools: ["Read", "Bash", "Grep"]
shell: bash
---

# NexusHub CLI Skill

Expert guide for using the `nh` command-line interface to interact with NexusHub.

## Quick Reference

### Authentication
```bash
# Login through the browser (production)
nh login --base-url=https://n.chatsoftware.cn

# For local development
nh login --base-url=http://localhost:2435

# Non-interactive login with an API key
nh login --api-key=nhk_xxx --base-url=https://n.chatsoftware.cn

# Check current user
nh whoami
```

### Unified Search Commands (All Entities)

All entities support fuzzy search with the same pattern:

```bash
nh <entity> search <query> [options]
```

**Common Options:**
- `--exact` - Exact match only
- `--limit <n>` - Max results (default: 20)
- `--page <n>` - Page number (default: 1)
- `--format <format>` - Output: `table` (default) or `json`

**Entity-Specific Options:**
- **Projects:** `--title-only` - Search titles only; `--archived` - only archived projects
- **Tasks:** `--title-only` - Search titles only (excludes subtasks)
- **Issues:** `--include-comments` - Search in comments
- **Users:** `--role <role>` - Filter by role (Admin|Staff|Client)

### List Commands with Filtering

```bash
# Projects
nh projects list [--stage <stage>] [--client-id <id>] [--archived] [--limit <n>]

# Tasks
nh tasks list [--project-id <id>] [--status <list>] [--priority <list>] 
              [--assignee <id>] [--sort-by <field>] [--sort-order <order>]

# Issues
nh issues list [--project-id <id>] [--archived] [--status <list>] 
               [--priority <list>] [--sort-by <field>]

# Clients
nh clients list [--status <status>] [--industry <industry>]

# Users
nh users list [--role <role>]
```

## Best Practices

### 1. Prefer Search for Discovery
Use `search` when you don't know exact IDs:
```bash
# Good: Find projects by name
nh projects search "website"

# Bad: Don't list all then manually filter
nh projects list | grep "website"  # Inefficient
```

### 2. Use Table Format for Human Review
Default table format shows key fields with full MongoDB IDs:
```bash
nh projects search "AI"
# Output: Full ID (24 chars), Title, Stage, Lead, Description
```

### 3. Use JSON Format for Scripting
```bash
# Get project ID for automation
PROJECT_ID=$(nh projects search "My Project" --format json --limit 1 | jq -r '.projects[0]._id')
```

### 4. Leverage Exact Match for IDs
```bash
# Search by exact slug
nh tasks search "TASK-001" --exact
nh issues search "ISSUE-123" --exact
```

### 5. Chain Commands Effectively
```bash
# Get project, then find its tasks
PROJECT_ID=$(nh projects search "Project Name" --exact --format json | jq -r '.projects[0]._id')
nh tasks list --project-id $PROJECT_ID
```

## Common Workflows

### Find Tasks in a Project
```bash
# Step 1: Find the project
PROJECT_ID=$(nh projects search "Project Name" --format json | jq -r '.projects[0]._id')

# Step 2: List all tasks in that project
nh tasks list --project-id $PROJECT_ID

# Step 3: Filter by status
nh tasks list --project-id $PROJECT_ID --status todo,in-progress
```

### Export Data for Reporting
```bash
# List or restore archived projects
nh projects list --archived
nh projects archive <id>
nh projects unarchive <id>

# Export all active projects as JSON
nh projects list --stage active --format json > active-projects.json

# Export high priority tasks
nh tasks list --priority high --format json > high-priority-tasks.json

# Get issue statistics
nh issues list --status open --format json | jq '.issues | length'
```

### Search Across All Content Types
```bash
# Find anything related to "authentication"
nh projects search "authentication"
nh tasks search "authentication"
nh issues search "authentication"
```

## Command Reference

### Output Formats

**Table Format (Default):**
- Shows full MongoDB ObjectIds (24 characters, not truncated)
- Truncates other fields with "..." suffix
- Includes pagination info and command hint
- Best for: Human review, quick lookups

**JSON Format:**
- Full API response with all fields
- Includes pagination metadata
- Best for: Scripting, automation, data export

### Pagination

All list and search commands support pagination:
- `--limit <n>` - Items per page (default: 20, max: 100)
- `--page <n>` - Page number (starting at 1)

Response includes:
```
Showing 1-20 of 150 items (Page 1 of 8)
→ nh projects search "query" --page 2
```

### ID Display

**Important:** CLI displays full MongoDB ObjectIds (e.g., `67c95731669e14fa93da02a2`)
- Never truncated in table output
- Always use full IDs for `get`, `update`, `delete` commands

## Troubleshooting

### "No items found"
- Check if query is too specific
- Try fuzzy search without `--exact`
- Verify filters aren't too restrictive

### API Errors
```bash
# Check authentication
nh whoami

# Login through the browser
nh login --base-url=https://n.chatsoftware.cn
```

### Empty Results
- Empty string query (`""`) returns all accessible items
- Check user permissions for the entity
- Verify filters match available values

## Examples

### Get Project Details
```bash
nh projects get 67c95731669e14fa93da02a2
```

### Get Issue Details
```bash
nh issues get 691efe2d8560c280464bf0aa
nh issues get https://n.chatsoftware.cn/issues/i-nh-example-0819
```

`nh issues get` rewrites attachment `fileUrl`s to absolute URLs and downloads issue and comment attachments to a temp directory, adding `localPath` on each file. Open image `localPath`s to inspect screenshots. Use `--no-download` to skip saving files.

```bash
nh issues attachments download <id> --out /tmp/issue-files

# Add a comment with screenshots
nh issues comment i-issue-0819 --body "已实现。" --attach shot.png --attach inbox.png

# Edit or soft-delete a comment (author or admin)
nh issues comment-update i-issue-0819 <commentId> --body "已实现，见截图。" --attach shot.png
nh issues comment-delete i-issue-0819 <commentId>
```

### Create Task
```bash
nh tasks create --data='{"title":"New Task","description":"Details","priority":"high","projectId":"67c95731669e14fa93da02a2"}'
```

### Update Issue Status
```bash
nh issues set-status 691efe2d8560c280464bf0aa in-progress
```

### Move an Issue to Another Project
```bash
nh issues move 691efe2d8560c280464bf0aa --project-id 67c95731669e14fa93da02a2
```

### Find Unassigned Tasks
```bash
nh tasks list --assignee unassigned
```

### Search Clients by Industry
```bash
nh clients search "technology"
```

### List Staff Members
```bash
nh users list --role Staff
```

## Environment Variables

```bash
# Production
export NEXUSHUB_API_KEY=nhk_xxx
export NEXUSHUB_BASE_URL=https://n.chatsoftware.cn

# Or for local development
export NEXUSHUB_BASE_URL=http://localhost:2435
export NODE_ENV=development
```

## File Locations

- CLI binary: `./dist/index.js`
- Source: `./src/commands/`
- Types: `./src/types/`
- API clients: `./src/api/`