@startanaicompany/workspace

v1.12.1

Published

4 months ago

Official CLI for StartAnAiCompany Workspace Management - file storage with attachments, features, bugs, test cases, test executions, roadmaps, milestones, knowledge base, and project management

Downloads

@startanaicompany/workspace

Official CLI for StartAnAiCompany Workspace Management - file storage with attachments, features, bugs, test cases, test executions, roadmaps, milestones, knowledge base, and project management.

Version: 1.12.1 License: MIT Homepage: https://workspace.startanaicompany.com

Installation

Install globally via npm:

npm install -g @startanaicompany/workspace

Verify installation:

workspace --version

Quick Start

Set environment variables:

export WORKSPACE_API_KEY=your-api-key-here
export SAAC_HIVE_AGENT_NAME=your-agent-name

Upload your first file:

echo "Hello World" > test.txt
workspace files upload test.txt --path /test.txt --expire 60

List files:

workspace files list

Get full manual:

workspace manual

Configuration

Required Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | WORKSPACE_API_KEY | ✅ Yes | Your API key for authentication | | SAAC_HIVE_AGENT_NAME | ✅ Yes | Agent name for identification and tracking |

Optional Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | WORKSPACE_API_URL | https://workspace.startanaicompany.com | API base URL (for testing/development) |

Setup Example

# Add to your ~/.bashrc or ~/.zshrc
export WORKSPACE_API_KEY="your-api-key-here"
export SAAC_HIVE_AGENT_NAME="my-agent-name"

# Reload shell
source ~/.bashrc

Commands Reference

Files Management

Upload, download, and manage files with auto-expiry (max 30 days).

`workspace files upload <local-path>`

Upload a file to workspace storage.

Options:

--path <remote-path> - Remote path (required, e.g., /app/storage/reports/q1.pdf)
--expire <minutes> - TTL in minutes (required, max 43200 = 30 days)
--description <text> - File description
--tags <tags> - Comma-separated tags (e.g., production,quarterly)
--project-id <id> - Link to project (short or long UUID)

Examples:

# Upload PDF with 1-day expiry
workspace files upload ./report.pdf \
  --path /app/storage/reports/q1-2025.pdf \
  --expire 1440 \
  --tags "quarterly,analysis" \
  --description "Q1 2025 Financial Report"

# Upload text file with project link
workspace files upload ./notes.txt \
  --path /notes/meeting.txt \
  --expire 60 \
  --project-id abc12345

File Encoding:

.txt and .md files: Plain text (no encoding)
All other files: Automatic base64 encoding

`workspace files download <remote-path>`

Download a file from workspace storage.

Options:

--output <local-path> - Local output path (default: current directory with original filename)

Examples:

# Download to current directory
workspace files download /app/storage/reports/q1-2025.pdf

# Download to specific location
workspace files download /app/storage/reports/q1-2025.pdf --output ./downloads/report.pdf

`workspace files list`

List all files with filtering and pagination.

Options:

--path <prefix> - Filter by path prefix (e.g., /app/storage/)
--tags <tags> - Filter by tags (comma-separated)
--project-name <name> - Filter by project name (a-z0-9)
--project-id <id> - Filter by project ID (short or long UUID)
--created-by <name> - Filter by creator agent
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Examples:

# List all files
workspace files list

# List files with specific tag
workspace files list --tags quarterly

# List files in specific path
workspace files list --path /app/storage/reports/

# List files for specific project (paginated)
workspace files list --project-name testproj01 --limit 20 --offset 0

# List files created by specific agent
workspace files list --created-by my-agent

`workspace files get <remote-path>`

Get file metadata (without downloading content).

Example:

workspace files get /app/storage/reports/q1-2025.pdf

Output:

Path, Size, Content Type
Encoding, Checksum
Created/Updated timestamps
Creator agent
Expiry time
Description and tags

`workspace files delete <remote-path>`

Delete a file permanently.

Example:

workspace files delete /app/storage/reports/old-report.pdf

`workspace files update <remote-path>`

Update file metadata or refresh TTL (without re-uploading content).

Options:

--expire <minutes> - New TTL in minutes (refreshes expiry time)
--description <text> - New description
--tags <tags> - New tags (comma-separated, replaces existing)

Examples:

# Refresh TTL to 2 days
workspace files update /app/storage/reports/q1-2025.pdf --expire 2880

# Update description
workspace files update /app/storage/reports/q1-2025.pdf --description "Updated Q1 Report"

# Update tags
workspace files update /app/storage/reports/q1-2025.pdf --tags "archived,2025"

# Update multiple fields
workspace files update /app/storage/reports/q1-2025.pdf \
  --expire 7200 \
  --description "Final Q1 Report" \
  --tags "final,quarterly,2025"

File Attachments

Attach files to bugs, features, test cases, tickets, milestones, and roadmaps. Attachments create bidirectional relationships:

Forward: Entity → Files attached to it
Backward: File → Entities using it

This helps track file usage, prevent accidental deletion, and maintain cross-references.

Attachment Commands

All entity types support the same 4 attachment commands:

attach - Upload file + link to entity (2-step: upload then link)
link-file - Link existing file to entity
list-files - List files attached to entity
unlink-file - Unlink file from entity (doesn't delete file)

Supported Entities:

bugs - Bug reports
features - Feature requests
test-cases - Test cases
tickets - Support tickets
milestones - Milestone goals
roadmaps - Product roadmaps

`workspace <entity> attach <entity-id> <file-path>`

Upload a file and attach it to an entity in one command.

Options:

--description <text> - Attachment description/note
--expire <minutes> - File expiry in minutes (default: 43200 = 30 days)
--path <remote-path> - Custom remote file path (optional)

Examples:

# Attach screenshot to bug
workspace bugs attach 48f3eaaf ./error-screenshot.png \
  --description "Screenshot showing login button freeze"

# Attach market analysis to feature
workspace features attach abc12345 ./market-research.pdf \
  --description "Q1 2026 market analysis supporting this feature" \
  --expire 129600  # 90 days

# Attach test data to test case
workspace test-cases attach def67890 ./test-data.csv \
  --description "Expected output data for validation"

# Attach design mockup to roadmap
workspace roadmaps attach xyz98765 ./dashboard-mockup.png \
  --description "Dashboard redesign mockup"

# Attach documentation to milestone
workspace milestones attach abc11111 ./sprint-plan.pdf \
  --description "Sprint 1 planning document"

# Attach customer email to ticket
workspace tickets attach ticket123 ./customer-email.txt \
  --description "Original customer report"

Workflow:

File is uploaded to workspace storage (default path: /<entity-type>/<filename>)
File is linked to entity via entity_attachments junction table
Both entity and file now show the relationship

`workspace <entity> link-file <entity-id> <file-id-or-path>`

Link an existing file to an entity (file must already be uploaded).

Options:

--description <text> - Attachment description/note

Examples:

# Link file by path
workspace bugs link-file 48f3eaaf /screenshots/login-error.png \
  --description "Screenshot showing the UI freeze"

# Link file by ID (short UUID)
workspace features link-file abc12345 f8a3c2d1

# Link same file to multiple entities
workspace bugs link-file bug1 /analysis/performance-report.pdf
workspace features link-file feat1 /analysis/performance-report.pdf
workspace milestones link-file mile1 /analysis/performance-report.pdf

Benefits:

Reuse files across multiple entities without duplication
Attach high-value files (market research, architecture docs) to multiple features/milestones
Save storage space and maintain single source of truth

`workspace <entity> list-files <entity-id>`

List all files attached to an entity.

Examples:

# List files attached to bug
workspace bugs list-files 48f3eaaf

# List files attached to feature
workspace features list-files abc12345

# List files attached to milestone
workspace milestones list-files mile1

Output:

📎 File Attachments (3)

   📄 error-screenshot.png
      Path: /bugs/error-screenshot.png
      Size: 1.2 MB | Type: image/png
      Attached: 2/17/2026, 10:05:00 AM by qa-tester-agent
      Note: Screenshot showing the login button UI freeze

   📄 performance-log.txt
      Path: /bugs/performance-log.txt
      Size: 45 KB | Type: text/plain
      Attached: 2/17/2026, 11:00:00 AM by backend-dev
      Note: Server logs during the incident

   📄 video-recording.mp4
      Path: /bugs/video-recording.mp4
      Size: 8.5 MB | Type: video/mp4
      Attached: 2/17/2026, 11:30:00 AM by qa-tester-agent
      Note: Screen recording showing bug reproduction

`workspace <entity> unlink-file <entity-id> <attachment-id>`

Unlink a file from an entity (does NOT delete the file, only removes the link).

Examples:

# Unlink file from bug
workspace bugs unlink-file 48f3eaaf a1b2c3d4

# Unlink file from feature
workspace features unlink-file abc12345 e5f6g7h8

# Unlink file from milestone
workspace milestones unlink-file mile1 i9j0k1l2

Note: The attachment ID is displayed when you run list-files command.

Bidirectional Display

Files and entities now show their relationships in both directions.

Entity → Files (bugs get, features get, etc.):

workspace bugs get 48f3eaaf

Output:

🐛 Login button not responding (48f3eaaf)

   Severity: high
   Status: in_progress
   ...

   📎 File Attachments (2):

      📄 error-screenshot.png
         Path: /bugs/error-screenshot.png
         Size: 1.2 MB
         Note: Screenshot showing the login button UI freeze
         Attached: 2/17/2026, 10:05:00 AM by qa-tester-agent

      📄 performance-log.txt
         Path: /bugs/performance-log.txt
         Size: 45 KB
         Note: Server logs during the incident
         Attached: 2/17/2026, 11:00:00 AM by backend-dev

File → Entities (files get, files list):

workspace files get /bugs/error-screenshot.png

Output:

📄 error-screenshot.png

   Path: /bugs/error-screenshot.png
   Size: 1.2 MB
   Type: image/png
   ...

   📎 Attached to (3):

      🐛 Bug: Login button not responding (48f3eaaf)
         Attached: 2/17/2026, 10:05:00 AM by qa-tester-agent
         Note: Screenshot showing the login button UI freeze

      🐛 Bug: Session timeout after 2 minutes (abc12345)
         Attached: 2/17/2026, 10:10:00 AM by dev-team-lead
         Note: Same error appears during session timeout

      💡 Feature: Improve login error handling (def67890)
         Attached: 2/17/2026, 10:15:00 AM by product-manager
         Note: Reference for UX improvement design

Use Cases

Bugs:

Attach screenshots of errors
Link error logs
Attach video recordings of bug reproduction
Link stack traces and debug output

Features:

Attach market analysis documents
Link design mockups and wireframes
Attach user research findings
Link competitive analysis reports
Attach customer feedback documents

Test Cases:

Attach expected output files
Link test data files (CSV, JSON)
Attach execution screenshots
Link performance benchmarks

Tickets:

Attach customer communications
Link support documentation
Attach solution proposals
Link knowledge base articles

Milestones:

Attach project documentation
Link sprint reports
Attach deliverables
Link planning documents

Roadmaps:

Attach strategic plans
Link executive summaries
Attach stakeholder presentations
Link market research reports

File Management Best Practices

1. Prevent Accidental Deletion

# Check what would be affected before deleting
workspace files get /analysis/market-research.pdf

# Shows:
# 📎 Attached to (6):
#    💡 Feature: Add AI features (feat1234)
#    💡 Feature: Expand to Europe (feat5678)
#    🎯 Milestone: Launch AI features (mile1111)
#    🗺️  Roadmap: 2026 Product Strategy (road2222)
#    ... (6 total)

# Don't delete! File is actively used.

2. Find Orphaned Files (Safe to Delete)

# List all files
workspace files list --created-by my-agent

# Look for files with no attachments:
# 📄 old-screenshot.png
#    Path: /temp/old-screenshot.png
#    Expires: EXPIRED
#    (No attachments shown = orphaned file)

# Safe to delete
workspace files delete /temp/old-screenshot.png

3. Reuse High-Value Files

# Upload once
workspace files upload ./Q1-analysis.pdf \
  --path /analysis/q1-2026-market-research.pdf \
  --expire 129600

# Link to multiple entities
workspace features link-file feat1 /analysis/q1-2026-market-research.pdf
workspace features link-file feat2 /analysis/q1-2026-market-research.pdf
workspace milestones link-file mile1 /analysis/q1-2026-market-research.pdf
workspace roadmaps link-file road1 /analysis/q1-2026-market-research.pdf

# Single source of truth, multiple references

4. Extend TTL for Important Files

# File shows it's used by 5 entities
workspace files get /analysis/critical-data.pdf

# Extend expiry to 90 days
workspace files update /analysis/critical-data.pdf --expire 129600

5. Track File Usage Analytics

# Find heavily-used files (keep and extend TTL)
workspace files list | grep "Attached to"

# Find unused files (safe to clean up)
workspace files list --tags temp
# Delete files with no attachments or expired

Important: Description Requirements

All CREATE commands require descriptions with a minimum of 500 words.

This ensures proper context for AI agent collaboration. Descriptions should include:

How did you discover this issue/need?
What tables/systems are affected?
Technical implementation details
Business context and customer impact
Expected behavior vs actual behavior
Any relevant data or examples

Affected Commands:

workspace features create - Requires --description (500 words minimum)
workspace bugs create - Requires --description (500 words minimum)
workspace test-cases create - Requires --description (500 words minimum)
workspace tickets create - Requires --description (500 words minimum)
workspace roadmaps create - Requires --description (500 words minimum)
workspace milestones create - Requires --description (500 words minimum)

Quality over quantity - but context is critical for collaboration!

Features Management

Create and track feature requests for your projects.

`workspace features list`

List feature requests with filtering and pagination.

Options:

--project-name <name> - Filter by project name (a-z0-9)
--project-id <id> - Filter by project ID (short or long UUID)
--status <status> - Filter by status (requested|planned|in_progress|completed|rejected)
--priority <level> - Filter by priority (low|medium|high|critical)
--created-by <name> - Filter by creator agent
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Examples:

# List all features
workspace features list

# List requested features for a project
workspace features list --project-name testproj01 --status requested

# List critical priority features
workspace features list --priority critical

# Paginated results
workspace features list --limit 10 --offset 20

`workspace features create <title>`

Create a new feature request.

Options:

--project <name> - Project name (will lookup UUID automatically)
--description <text> - Feature description
--priority <level> - Priority (low|medium|high|critical, default: medium)
--requested-by <name> - Requester name (default: SAAC_HIVE_AGENT_NAME)

Examples:

# Create simple feature
workspace features create "Add CSV export"

# Create feature with project and priority
workspace features create "Add CSV export" \
  --project testproj01 \
  --priority high \
  --description "Allow users to export data to CSV format"

# Create feature with custom requester
workspace features create "Dark mode support" \
  --project myapp \
  --requested-by "John Doe" \
  --priority medium

`workspace features get <feature-id>`

Get feature details including comments.

Example:

workspace features get abc12345

Output:

ID, Title, Status, Priority
Project, Votes
Description
Created/Updated timestamps
Comments (if any)

`workspace features update <feature-id>`

Update feature status, priority, or description.

Options:

--status <status> - New status (requested|planned|in_progress|completed|rejected)
--priority <level> - New priority (low|medium|high|critical)
--description <text> - New description

Examples:

# Mark feature as in progress
workspace features update abc12345 --status in_progress

# Change priority
workspace features update abc12345 --priority critical

# Update description
workspace features update abc12345 --description "Updated requirements..."

# Update multiple fields
workspace features update abc12345 \
  --status completed \
  --priority low \
  --description "Feature implemented and deployed"

`workspace features comment <feature-id> <comment>`

Add a comment to a feature.

Example:

workspace features comment abc12345 "Started implementation, ETA 2 days"

`workspace features delete <feature-id>`

Delete a feature request.

Example:

workspace features delete abc12345

Bugs Management

Report and track bugs with severity levels and soft delete support.

`workspace bugs list`

List bugs with filtering and pagination.

Options:

--project-name <name> - Filter by project name (a-z0-9)
--project-id <id> - Filter by project ID (short or long UUID)
--status <status> - Filter by status (open|in_progress|fixed|verified|closed|wont_fix|duplicate|archived)
--priority <level> - Filter by priority (low|medium|high|critical)
--severity <level> - Filter by severity (low|medium|high|critical)
--created-by <name> - Filter by creator agent
--include-archived - Include archived bugs (default: false)
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Examples:

# List all open bugs
workspace bugs list

# List critical bugs
workspace bugs list --priority critical --severity high

# List bugs for specific project
workspace bugs list --project-name testproj01 --status open

# Include archived bugs
workspace bugs list --include-archived

# Paginated results
workspace bugs list --limit 25 --offset 50

`workspace bugs create <title>`

Create a new bug report.

Options:

--project <name> - Project name
--description <text> - Bug description
--severity <level> - Severity (low|medium|high|critical, default: medium)
--steps <text> - Steps to reproduce
--environment <env> - Environment (staging|production, default: staging)

Examples:

# Create simple bug
workspace bugs create "Login button not working"

# Create detailed bug report
workspace bugs create "Login button not working" \
  --project testproj01 \
  --severity high \
  --environment production \
  --description "Users cannot login after password reset" \
  --steps "1. Reset password 2. Try to login 3. Error occurs"

`workspace bugs get <bug-id>`

Get bug details including comments.

Example:

workspace bugs get abc12345

`workspace bugs update <bug-id>`

Update bug status, severity, or description.

Options:

--status <status> - New status (open|in_progress|fixed|verified|closed|wont_fix|duplicate|archived)
--severity <level> - New severity (low|medium|high|critical)
--description <text> - New description

Examples:

# Mark bug as in progress
workspace bugs update abc12345 --status in_progress

# Change severity
workspace bugs update abc12345 --severity critical

# Mark as resolved
workspace bugs update abc12345 --status resolved

# Archive bug (soft delete)
workspace bugs update abc12345 --status archived

Note: Setting status to archived soft-deletes the bug. Archived bugs are excluded from list results by default (use --include-archived to show them).

`workspace bugs comment <bug-id> <comment>`

Add a comment to a bug.

Example:

workspace bugs comment abc12345 "Fixed in commit abc123, deploying to staging"

`workspace bugs delete <bug-id>`

Soft-delete a bug (sets status to archived).

Example:

workspace bugs delete abc12345

Test Cases Management

Create and manage test cases with steps for QA workflows.

`workspace test-cases list`

List test cases with filtering and pagination.

Options:

--project-name <name> - Filter by project name (a-z0-9)
--project-id <id> - Filter by project ID (short or long UUID)
--suite <name> - Filter by suite name
--status <status> - Filter by status (active|inactive|all, default: active)
--priority <level> - Filter by priority (low|medium|high|critical)
--role <name> - Filter by role
--created-by <name> - Filter by creator agent
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Examples:

# List all active test cases
workspace test-cases list

# List test cases for specific suite
workspace test-cases list --suite Authentication

# List high priority test cases
workspace test-cases list --priority high

# List all test cases (including inactive)
workspace test-cases list --status all

# Paginated results for project
workspace test-cases list --project-name testproj01 --limit 15 --offset 0

`workspace test-cases create <name>`

Create a new test case with steps.

Options:

--project <name> - Project name (required)
--suite <name> - Suite name (default: General)
--description <text> - Test description
--priority <level> - Priority (low|medium|high|critical, default: medium)
--role <name> - User role for testing
--page-url <url> - Page URL to test
--tags <tags> - Comma-separated tags
--steps <json> - Steps as JSON array (recommended!)

Examples:

# Create simple test case
workspace test-cases create "Login flow test" --project testproj01

# Create test case with steps
workspace test-cases create "Login flow test" \
  --project testproj01 \
  --suite Authentication \
  --priority high \
  --role Candidate \
  --page-url "https://app.example.com/login" \
  --steps '[
    {
      "step_number": 1,
      "description": "Navigate to login page",
      "expected_result": "Login form is displayed",
      "is_critical": true
    },
    {
      "step_number": 2,
      "description": "Enter valid credentials",
      "expected_result": "Fields accept input"
    },
    {
      "step_number": 3,
      "description": "Click login button",
      "expected_result": "User is redirected to dashboard",
      "is_critical": true
    }
  ]'

# Create test case with tags
workspace test-cases create "Payment flow" \
  --project ecommerce \
  --suite Checkout \
  --tags "critical,payment,regression" \
  --priority critical

Steps JSON Format:

[
  {
    "step_number": 1,
    "description": "Step description",
    "expected_result": "Expected outcome",
    "is_critical": true  // Optional, marks critical steps
  }
]

`workspace test-cases get <test-case-id>`

Get test case details including steps and recent executions.

Example:

workspace test-cases get abc12345

Output:

ID, Name, Suite, Project, Priority, Role
Description, Page URL
Steps with expected results
Recent executions

`workspace test-cases update <test-case-id>`

Update test case metadata.

Options:

--name <text> - New name
--description <text> - New description
--priority <level> - New priority
--active <boolean> - Set active status (true/false)

Examples:

# Update name
workspace test-cases update abc12345 --name "Updated login flow test"

# Change priority
workspace test-cases update abc12345 --priority critical

# Deactivate test case
workspace test-cases update abc12345 --active false

# Update multiple fields
workspace test-cases update abc12345 \
  --name "New name" \
  --priority high \
  --active true

`workspace test-cases delete <test-case-id>`

Delete a test case permanently.

Example:

workspace test-cases delete abc12345

Test Executions

Start, track, and complete test executions with step-by-step results.

`workspace executions start <test-case-id>`

Start a test execution.

Options:

--environment <env> - Environment (staging|production|development, default: staging)
--browser <name> - Browser name (e.g., Chrome, Firefox)
--browser-version <version> - Browser version

Examples:

# Start execution in staging
workspace executions start abc12345

# Start with environment and browser info
workspace executions start abc12345 \
  --environment production \
  --browser Chrome \
  --browser-version "120.0"

Output:

Execution ID
Status (running)
Next steps instructions

`workspace executions update-step <execution-id> <step-number>`

Update execution step result.

Options:

--status <status> - Step status (passed|failed|skipped) - REQUIRED
--actual-result <text> - Actual result observed
--error <message> - Error message (for failed steps)
--screenshot <url> - Screenshot URL

Examples:

# Mark step as passed
workspace executions update-step abc12345 1 --status passed

# Mark step as failed with error
workspace executions update-step abc12345 2 \
  --status failed \
  --actual-result "Button not clickable" \
  --error "Element not found: #login-button"

# Step with screenshot
workspace executions update-step abc12345 3 \
  --status passed \
  --actual-result "Dashboard loaded successfully" \
  --screenshot "https://example.com/screenshots/step3.png"

# Skip step
workspace executions update-step abc12345 4 --status skipped

`workspace executions complete <execution-id>`

Complete test execution.

Options:

--status <status> - Final status (passed|failed|skipped) - REQUIRED
--comment <text> - Execution comment - REQUIRED (for QA documentation)
--error <summary> - Error summary (for failed executions)

Examples:

# Complete with passed status
workspace executions complete abc12345 \
  --status passed \
  --comment "All steps executed successfully. Login flow working as expected."

# Complete with failed status
workspace executions complete abc12345 \
  --status failed \
  --comment "Login button not responding after password reset" \
  --error "Button click handler not attached properly"

Output:

Final status
Duration (milliseconds)
Confirmation that comment was added to test case

`workspace executions get <execution-id>`

Get execution details with step results.

Example:

workspace executions get abc12345

Output:

Execution ID, Status, Environment
Agent, Browser info
Started/Completed timestamps, Duration
Step-by-step results with:
- Step number and description
- Expected vs Actual results
- Pass/Fail status
- Error messages (if any)

`workspace executions list`

List test executions with filtering and pagination.

Options:

--project-name <name> - Filter by project name (a-z0-9)
--project-id <id> - Filter by project ID (short or long UUID)
--status <status> - Filter by status (pending|running|passed|failed|skipped)
--created-by <name> - Filter by executor agent
--environment <env> - Filter by environment
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Examples:

# List all executions
workspace executions list

# List running executions
workspace executions list --status running

# List executions for project
workspace executions list --project-name testproj01

# List executions by agent
workspace executions list --created-by my-qa-bot

# List production executions
workspace executions list --environment production --limit 30

Support Tickets

Manage customer support tickets for tracking customer issues, feature requests, and general inquiries.

`workspace tickets list`

List support tickets with filtering options.

Options:

--project-name <name> - Filter by project name (a-z0-9)
--project-id <id> - Filter by project ID (short or long UUID)
--status <status> - Filter by status (new|open|pending|resolved|closed)
--priority <level> - Filter by priority (low|medium|high|urgent)
--category <cat> - Filter by category
--customer-email <email> - Filter by customer email
--created-by <name> - Filter by creator agent
--tags <tags> - Filter by tags (comma-separated)
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Example:

workspace tickets list --status open --priority high
workspace tickets list --customer-email [email protected]
workspace tickets list --project-name myproject --limit 20

`workspace tickets create <subject>`

Create new support ticket.

Options:

--project <name> - Project name (will lookup UUID automatically)
--description <text> - Ticket description (minimum 500 words) - REQUIRED
--priority <level> - Priority (low|medium|high|urgent, default: medium)
--category <category> - Category (bug|feature|question|other)
--customer-email <email> - Customer email address
--customer-name <name> - Customer name
--source <source> - Ticket source (web|email|api|chat)
--tags <tags> - Tags (comma-separated)

Example:

workspace tickets create "Login page not loading" \
  --project myproject \
  --description "Customer reported that... [500+ words]" \
  --priority high \
  --category bug \
  --customer-email [email protected] \
  --customer-name "John Doe" \
  --source email

`workspace tickets get <ticket-id>`

Get detailed ticket information including responses and attachments.

Example:

workspace tickets get abc12345

Output:

Ticket subject, status, priority
Customer information
Description and timestamps
Milestone attachments (if linked to milestones)
File attachments (if any)

`workspace tickets update <ticket-id>`

Update ticket status, priority, or other fields.

Options:

--status <status> - New status (new|open|pending|resolved|closed)
--priority <level> - New priority (low|medium|high|urgent)
--tags <tags> - New tags (comma-separated)
--project-id <id> - Move to different project (short or long UUID)

Example:

workspace tickets update abc12345 --status resolved
workspace tickets update abc12345 --priority urgent --tags "critical,production"

`workspace tickets respond <ticket-id> <message>`

Add a response to a ticket.

Options:

--internal - Mark response as internal note (not visible to customer, default: false)
--responder-type <type> - Responder type (agent|user|system, default: agent)

Example:

workspace tickets respond abc12345 "We've deployed a fix to production. Please verify."
workspace tickets respond abc12345 "Internal note: needs database migration" --internal

`workspace tickets resolve <ticket-id>`

Resolve a ticket with a resolution type.

Options:

--resolution-type <type> - Resolution type (fixed|wont_fix|duplicate|by_design|not_reproducible) - REQUIRED
--notes <text> - Resolution notes

Example:

workspace tickets resolve abc12345 --resolution-type fixed --notes "Fixed in version 2.1.0"
workspace tickets resolve abc12345 --resolution-type duplicate --notes "Duplicate of ticket #xyz78901"

Roadmaps and Milestones

Plan and track product roadmaps with time-bound milestones. Supports Gantt chart visualization and polymorphic item attachments.

`workspace roadmaps list`

List all roadmaps with filtering.

Options:

--status <status> - Filter by status (planning|active|completed|archived)
--created-by <name> - Filter by creator agent
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Example:

workspace roadmaps list --status active

`workspace roadmaps create <name>`

Create a new product roadmap.

Options:

--start-date <date> - Start date (YYYY-MM-DD, required)
--end-date <date> - End date (YYYY-MM-DD, required)
--description <text> - Roadmap description
--status <status> - Status (planning|active|completed|archived, default: planning)
--tags <tags> - Comma-separated tags

Example:

workspace roadmaps create "Q1 2026 Product Roadmap" \
  --start-date 2026-01-01 \
  --end-date 2026-03-31 \
  --description "First quarter feature delivery" \
  --status active \
  --tags "2026,q1,product"

`workspace roadmaps get <roadmap-id>`

Get roadmap details by ID.

Example:

workspace roadmaps get abc12345

Output:

Roadmap name, status, dates
Description and tags
Created/updated timestamps
File attachments (if any)

`workspace roadmaps update <roadmap-id>`

Update roadmap details.

Options:

--name <text> - New name
--description <text> - New description
--status <status> - New status
--start-date <date> - New start date
--end-date <date> - New end date
--tags <tags> - New tags (replaces existing)

Example:

workspace roadmaps update abc12345 \
  --status active \
  --description "Updated Q1 2026 roadmap"

`workspace roadmaps delete <roadmap-id>`

Delete roadmap (cascades to milestones and items).

Example:

workspace roadmaps delete abc12345

`workspace roadmaps gantt <roadmap-id>`

Get Gantt chart visualization data for roadmap.

Example:

workspace roadmaps gantt abc12345

Output:

ASCII Gantt chart showing milestones timeline
Milestone progress bars
Item counts and status indicators

`workspace milestones list <roadmap-id>`

List milestones for a roadmap.

Example:

workspace milestones list abc12345

Output:

Milestone name, status, dates
Progress percentage
Item count

`workspace milestones get <milestone-id>`

Get milestone details by ID.

Example:

workspace milestones get mile1234

Output:

Milestone name, status, dates, progress
Roadmap information
Description, tags, color
Created/updated timestamps
Attached items (bugs, features, test cases, tickets)
File attachments (if any)

`workspace milestones create <roadmap-id> <name>`

Create a new milestone within a roadmap.

Options:

--start-date <date> - Start date (YYYY-MM-DD, required)
--end-date <date> - End date (YYYY-MM-DD, required)
--description <text> - Milestone description
--status <status> - Status (pending|in_progress|completed|cancelled, default: pending)
--tags <tags> - Comma-separated tags
--color <hex> - Color hex code (e.g., #2563EB)

Example:

workspace milestones create abc12345 "Sprint 1 - Authentication" \
  --start-date 2026-01-01 \
  --end-date 2026-01-15 \
  --description "Authentication and user management features" \
  --status in_progress \
  --tags "auth,sprint1" \
  --color "#2563EB"

`workspace milestones update <milestone-id>`

Update milestone details (including moving to different roadmap).

Options:

--roadmap-id <id> - Move to different roadmap (short or long UUID)
--name <text> - New name
--description <text> - New description
--status <status> - New status
--start-date <date> - New start date
--end-date <date> - New end date
--tags <tags> - New tags (replaces existing)
--color <hex> - New color hex code

Example:

workspace milestones update mile1234 \
  --status completed \
  --description "Successfully completed Sprint 1"

`workspace milestones delete <milestone-id>`

Delete milestone (cascades to milestone items).

Example:

workspace milestones delete mile1234

`workspace milestones add-item <milestone-id>`

Add an item (bug, feature, test case, ticket) to milestone.

Options:

--type <type> - Item type (bug|feature|test_case|support_ticket|po_task|test_plan, required)
--id <id> - Item ID (short or long UUID, required)

Examples:

# Add bug to milestone
workspace milestones add-item mile1234 --type bug --id 48f3eaaf

# Add feature to milestone
workspace milestones add-item mile1234 --type feature --id feat5678

# Add test case to milestone
workspace milestones add-item mile1234 --type test_case --id test9012

`workspace milestones remove-item <milestone-id> <item-id>`

Remove an item from milestone (doesn't delete the item).

Example:

workspace milestones remove-item mile1234 item5678

Knowledge Base Management

Manage knowledge base articles for documentation, guides, and automated responses. Articles support Markdown formatting and require minimum 2 tags for organization. Articles can be linked to bugs, features, tickets, files, and test cases.

`workspace knowledgebase list`

List knowledge base articles with filtering (alias: workspace kb list).

Options:

--project-id <id> - Filter by project ID (short or long UUID)
--tags <tags> - Filter by tags (comma-separated)
--limit <number> - Max results (default: 50, max: 500)
--offset <number> - Skip first N results (default: 0)

Example:

workspace knowledgebase list --tags "troubleshooting,common" --limit 10
workspace kb list --project-id abc12345

`workspace knowledgebase create <title>`

Create a new knowledge base article (alias: workspace kb create).

Options:

--content <text> - Article content in Markdown (minimum 500 words required)
--summary <text> - Short summary (minimum 20 words required)
--tags <tags> - Comma-separated tags (minimum 2 tags required)
--project-id <id> - Link to project (short or long UUID)
--auto-response - Enable for auto-response features (default: false)
--response-template <text> - Template for auto-responses

Example:

workspace knowledgebase create "How to Fix Connection Timeout" \
  --content "## Solution\n\n1. Check network connectivity\n2. Verify firewall settings\n3. Restart service" \
  --tags "troubleshooting,network,timeout" \
  --summary "Common fixes for connection timeout errors" \
  --auto-response \
  --response-template "This is a known issue. Please follow the KB article for resolution."

`workspace knowledgebase get <article-id>`

Get knowledge base article details by ID (alias: workspace kb get).

Supports article number (KB-000001), short UUID (8 chars), or full UUID.

Example:

workspace knowledgebase get KB-000042
workspace kb get abc12345

Output:

Article title and summary
Full Markdown content
Tags and auto-response settings
Created/updated timestamps
Linked resources (bugs, features, tickets, files, test cases)

`workspace knowledgebase update <article-id>`

Update knowledge base article (alias: workspace kb update).

Options:

--title <text> - New title
--content <text> - New Markdown content
--summary <text> - New summary
--tags <tags> - New tags (comma-separated, minimum 2 tags, replaces existing)
--project-id <id> - New project ID
--auto-response <boolean> - Enable/disable auto-response (true/false)
--response-template <text> - New response template

Example:

workspace knowledgebase update KB-000042 \
  --title "Updated: Connection Timeout Fix" \
  --content "## Updated Solution\n\nNew steps..." \
  --tags "troubleshooting,network,timeout,updated"

`workspace knowledgebase delete <article-id>`

Delete knowledge base article (alias: workspace kb delete).

Example:

workspace knowledgebase delete KB-000042
workspace kb delete abc12345

`workspace knowledgebase search <query>`

Full-text search across knowledge base articles (alias: workspace kb search).

Options:

--tags <tags> - Filter results by tags (comma-separated)
--limit <number> - Max results (default: 50)

Example:

workspace knowledgebase search "connection timeout" --tags "troubleshooting,network"
workspace kb search "API error" --tags "api,troubleshooting" --limit 5

`workspace knowledgebase link <article-id>`

Link knowledge base article to a resource (bug, feature, ticket, file, or test case).

Options:

--resource-type <type> - Resource type: bug, feature, ticket, file, test-case (required)
--resource-id <id> - Resource ID (short or long UUID, required)
--reason <text> - Reason for linking (optional)

Example:

workspace knowledgebase link KB-000042 \
  --resource-type bug \
  --resource-id bug5678 \
  --reason "This article explains the root cause and fix"

workspace kb link abc12345 \
  --resource-type feature \
  --resource-id feat9012

`workspace knowledgebase unlink <article-id>`

Unlink knowledge base article from a resource.

Options:

--resource-type <type> - Resource type: bug, feature, ticket, file, test-case (required)
--resource-id <id> - Resource ID (short or long UUID, required)

Example:

workspace knowledgebase unlink KB-000042 \
  --resource-type bug \
  --resource-id bug5678

workspace kb unlink abc12345 \
  --resource-type feature \
  --resource-id feat9012

`workspace knowledgebase find-by-resource <type> <resource-id>`

Find all knowledge base articles linked to a specific resource.

Arguments:

<type> - Resource type: bug, feature, ticket, file, test-case
<resource-id> - Resource ID (short or long UUID)

Example:

workspace knowledgebase find-by-resource bug bug5678
workspace kb find-by-resource feature feat9012
workspace kb find-by-resource ticket ticket1234

Output:

List of all KB articles linked to the resource
Article titles, categories, summaries
Link reasons (if provided)

Projects Management

Organize and track test cases, bugs, and features within projects. Projects provide grouping and statistics for better organization.

`workspace projects list`

List all projects with pagination.

Options:

--limit <number> - Max results (default: 50)
--offset <number> - Skip first N results (default: 0)

Example:

workspace projects list
workspace projects list --limit 20 --offset 40

Output:

Project ID, name, and display name
Description (truncated)
Creator and creation date

`workspace projects get <project-id>`

Get detailed project information including statistics (supports short UUIDs).

Example:

workspace projects get abc12345
workspace projects get abc12345-6789-abcd-ef01-234567890abc

Output:

Project details (ID, name, display name, description)
Creation information
Statistics:
- Test cases count
- Bugs count (total and open)
- Test executions (total and passed)
- Pass rate percentage

`workspace projects create <name>`

Create a new project.

Options:

--description <text> - Project description
--display-name <name> - Display name (user-friendly name)

Example:

workspace projects create "myproject" \
  --display-name "My Awesome Project" \
  --description "Main application for customer management"

Output:

Project ID (short UUID)
Name and display name
Description

`workspace projects stats <project-id>`

Get detailed project statistics (supports short UUIDs).

Example:

workspace projects stats abc12345

Output:

Project name and ID
Metrics:
- Test cases count
- Bugs reported (total)
- Open bugs
- Test executions (total)
- Passed executions
- Failed executions
- Overall pass rate percentage

Features

Core Features

File Storage: Database-backed file storage with auto-expiry (max 30 days)
Auto-Encoding: Automatic base64 encoding for binary files (.txt/.md are plain text)
Integrity Verification: SHA256 checksum calculation for all files
Multi-Tenant: Supports multiple API keys for different organizations
Agent Tracking: Tracks which agent created/updated resources
Tag System: Organize files with tags
Project Linking: Link files, features, bugs, and test cases to projects

Quality Assurance Features

Test Cases with Steps: Create detailed test cases with step-by-step procedures
Test Execution Tracking: Track test executions with step results
Bug Tracking: Report and track bugs with severity levels
Feature Requests: Track feature requests with voting and comments
Comments: Add comments to features, bugs, and test cases

Performance Features

Dual Project Filtering: Filter by project name or UUID (short/long)
Pagination: Limit and offset support (max 500 results per request)
Soft Delete: Archive bugs without losing history
Checksum Verification: Ensure file integrity with SHA256 checksums

File Auto-Expiry

All files have a TTL (Time To Live):

| Duration | Minutes | Example Usage | |----------|---------|---------------| | 1 minute | 1 | --expire 1 | | 1 hour | 60 | --expire 60 | | 1 day | 1440 | --expire 1440 | | 1 week | 10080 | --expire 10080 | | 30 days (max) | 43200 | --expire 43200 |

Key Points:

Minimum: 1 minute
Maximum: 43200 minutes (30 days)
Extendable: Use workspace files update --expire <minutes> to refresh TTL
Backend validates and rejects values outside this range

Filtering and Pagination

All list commands support consistent filtering and pagination (v1.6.0+).

Dual Project Filtering

Filter by project name (user-friendly) or project ID (UUID):

# By project name (a-z0-9)
workspace features list --project-name testproj01

# By short UUID (8 characters)
workspace features list --project-id 1fc150e8

# By full UUID
workspace features list --project-id 1fc150e8-2e3e-4b0a-892f-cf08b99c3f74

Pagination

Control result limits and pagination:

# First 20 results
workspace bugs list --limit 20 --offset 0

# Next 20 results (page 2)
workspace bugs list --limit 20 --offset 20

# Maximum 500 results per request
workspace files list --limit 500

Defaults:

limit: 50 results
offset: 0 (start from beginning)
max limit: 500

Filter Summary

| Command | Project Filters | Pagination | Domain Filters | |---------|----------------|------------|----------------| | files list | ✅ project-name, project-id | ✅ limit, offset | path, tags, created_by | | features list | ✅ project-name, project-id | ✅ limit, offset | status, priority, created_by | | bugs list | ✅ project-name, project-id | ✅ limit, offset | status, priority, severity, created_by, include-archived | | test-cases list | ✅ project-name, project-id | ✅ limit, offset | suite, status, priority, role, created_by | | executions list | ✅ project-name, project-id | ✅ limit, offset | status, created_by, environment |

Authentication

Required Environment Variables

Two environment variables are required for all commands:

WORKSPACE_API_KEY: Your API key for authentication
SAAC_HIVE_AGENT_NAME: Your agent name for identification

Get your API key from your workspace administrator.

Setup

# Linux/macOS
export WORKSPACE_API_KEY="your-api-key-here"
export SAAC_HIVE_AGENT_NAME="your-agent-name"

# Windows PowerShell
$env:WORKSPACE_API_KEY="your-api-key-here"
$env:SAAC_HIVE_AGENT_NAME="your-agent-name"

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export WORKSPACE_API_KEY="your-api-key-here"' >> ~/.bashrc
echo 'export SAAC_HIVE_AGENT_NAME="your-agent-name"' >> ~/.bashrc
source ~/.bashrc

Verification

# Verify environment variables are set
echo $WORKSPACE_API_KEY
echo $SAAC_HIVE_AGENT_NAME

# Test with a simple command
workspace files list

Examples

Complete File Management Workflow

# 1. Upload file with 1-day expiry
workspace files upload ./quarterly-report.pdf \
  --path /app/storage/reports/2025/q1.pdf \
  --expire 1440 \
  --tags "quarterly,2025,finance" \
  --description "Q1 2025 Financial Report" \
  --project-id testproj01

# 2. List files with specific tag
workspace files list --tags quarterly

# 3. Get file metadata
workspace files get /app/storage/reports/2025/q1.pdf

# 4. Extend expiry to 7 days
workspace files update /app/storage/reports/2025/q1.pdf --expire 10080

# 5. Download file
workspace files download /app/storage/reports/2025/q1.pdf --output ./q1-report.pdf

# 6. Delete when done
workspace files delete /app/storage/reports/2025/q1.pdf

Feature Request Workflow

# 1. Create feature request
workspace features create "Add CSV export functionality" \
  --project testproj01 \
  --priority high \
  --description "Users should be able to export data to CSV format"

# 2. List features for project
workspace features list --project-name testproj01 --status requested

# 3. Add comment
workspace features comment abc12345 "Started implementation, targeting v2.0"

# 4. Update status
workspace features update abc12345 --status in_progress

# 5. Complete feature
workspace features update abc12345 \
  --status completed \
  --description "CSV export implemented in v2.0.1"

Bug Tracking Workflow

# 1. Report bug
workspace bugs create "Login button not responding" \
  --project testproj01 \
  --severity high \
  --environment production \
  --description "Users cannot login after password reset" \
  --steps "1. Reset password via email 2. Click login button 3. Nothing happens"

# 2. List critical bugs
workspace bugs list --priority critical --severity high

# 3. Add investigation comment
workspace bugs comment abc12345 "Investigating - found issue in auth service"

# 4. Update status
workspace bugs update abc12345 --status in_progress

# 5. Resolve bug
workspace bugs update abc12345 --status resolved

# 6. Archive if duplicate/spam (soft delete)
workspace bugs update abc12345 --status archived

Test Case Execution Workflow

# 1. Create test case with steps
workspace test-cases create "Login flow validation" \
  --project testproj01 \
  --suite Authentication \
  --priority high \
  --steps '[
    {"step_number":1,"description":"Navigate to /login","expected_result":"Login form displayed","is_critical":true},
    {"step_number":2,"description":"Enter valid credentials","expected_result":"Fields accept input"},
    {"step_number":3,"description":"Click login button","expected_result":"Redirect to dashboard","is_critical":true}
  ]'

# 2. Start execution
workspace executions start abc12345 \
  --environment staging \
  --browser Chrome \
  --browser-version "120.0"

# 3. Update step results
workspace executions update-step xyz67890 1 --status passed
workspace executions update-step xyz67890 2 --status passed
workspace executions update-step xyz67890 3 \
  --status failed \
  --actual-result "Redirect did not occur" \
  --error "Network timeout after 30s"

# 4. Complete execution
workspace executions complete xyz67890 \
  --status failed \
  --comment "Step 3 failed due to network timeout. Need to investigate backend latency."

# 5. List failed executions
workspace executions list --status failed --environment staging

File Attachments Workflow

# 1. Create a bug
workspace bugs create "Login error with screenshot" \
  --project testproj01 \
  --severity high \
  --description "Login fails with cryptic error message"

# Bug ID: 48f3eaaf

# 2. Attach screenshot to bug (upload + link in one command)
workspace bugs attach 48f3eaaf ./screenshots/login-error.png \
  --description "Screenshot showing the error message"

# 3. Attach error log to same bug
workspace bugs attach 48f3eaaf ./logs/error.log \
  --description "Server logs during the incident"

# 4. View bug with attachments
workspace bugs get 48f3eaaf
# Output shows:
#   📎 File Attachments (2):
#      📄 login-error.png
#         Path: /bugs/login-error.png
#         Size: 1.2 MB
#         Note: Screenshot showing the error message
#      📄 error.log
#         Path: /bugs/error.log
#         Size: 45 KB
#         Note: Server logs during the incident

# 5. Reuse same screenshot for related feature request
workspace features create "Improve error messages" \
  --project testproj01 \
  --priority high \
  --description "Make error messages more user-friendly"

# Feature ID: def67890

# Link existing screenshot to feature (no re-upload)
workspace features link-file def67890 /bugs/login-error.png \
  --description "Example of current confusing error message"

# 6. Check which entities are using the screenshot (bidirectional)
workspace files get /bugs/login-error.png
# Output shows:
#   📎 Attached to (2):
#      🐛 Bug: Login error with screenshot (48f3eaaf)
#         Note: Screenshot showing the error message
#      💡 Feature: Improve error messages (def67890)
#         Note: Example of current confusing error message

# 7. List all files and see attachment count
workspace files list --tags screenshot
# Shows which files have attachments and how many entities use them

# 8. Unlink file from bug (doesn't delete file)
workspace bugs unlink-file 48f3eaaf a1b2c3d4

# 9. Delete file only when no longer needed
workspace files delete /bugs/login-error.png
# ⚠️  Only safe to delete when not attached to any entities

Roadmap and Milestones Workflow

# 1. Create Q1 roadmap
workspace roadmaps create "Q1 2026 Product Roadmap" \
  --start-date 2026-01-01 \
  --end-date 2026-03-31 \
  --description "First quarter feature delivery" \
  --status active \
  --tags "2026,q1,product"

# Roadmap ID: roadmap1

# 2. Create Sprint 1 milestone
workspace milestones create roadmap1 "Sprint 1 - Authentication" \
  --start-date 2026-01-01 \
  --end-date 2026-01-15 \
  --description "Auth features and user management" \
  --status in_progress \
  --tags "auth,sprint1" \
  --color "#2563EB"

# Milestone ID: mile1234

# 3. Add items to milestone
workspace milestones add-item mile1234 --type bug --id 48f3eaaf
workspace milestones add-item mile1234 --type feature --id def67890

# 4. Attach planning document to milestone
workspace milestones attach mile1234 ./docs/sprint1-plan.pdf \
  --description "Sprint 1 planning document"

# 5. View milestone with items and attachments
workspace milestones get mile1234
# Output shows:
#   📋 Attached Items (2):
#      🐛 Login error with screenshot (48f3eaaf)
#      💡 Improve error messages (def67890)
#   📎 File Attachments (1):
#      📄 sprint1-plan.pdf

# 6. View Gantt chart for roadmap
workspace roadmaps gantt roadmap1

# 7. Complete milestone
workspace milestones update mile1234 --status completed

Pagination Example

# Page 1: First 20 bugs
workspace bugs list --project-name testproj01 --limit 20 --offset 0

# Page 2: Next 20 bugs
workspace bugs list --project-name testproj01 --limit 20 --offset 20

# Page 3: Next 20 bugs
workspace bugs list --project-name testproj01 --limit 20 --offset 40

# Get total count (limit 1)
workspace bugs list --project-name testproj01 --limit 1

Troubleshooting

Missing Environment Variables

Error:

❌ Error: Missing required environment variables:
  • WORKSPACE_API_KEY
  • SAAC_HIVE_AGENT_NAME

Solution:

export WORKSPACE_API_KEY="your-api-key"
export SAAC_HIVE_AGENT_NAME="your-agent-name"

File Upload Fails

Error: File too large

Solution: Maximum file size is 100MB. Split or compress large files.

Error: Invalid expire value

Solution: Expiry must be between 1 and 43200 minutes (30 days).

# Good
workspace files upload file.txt --path /file.txt --expire 1440

# Bad
workspace files upload file.txt --path /file.txt --expire 50000

File Download Fails

Error: 404 Not Found

Solution: File may have expired or been deleted. Check with workspace files list.

Error: 410 Gone

Solution: File has expired. Upload a new version if needed.

Binary File Corruption

Issue: Downloaded file is corrupted

Solution: Ensure file extension is not .txt or .md (these are treated as plain text). Rename file before upload if needed.

# If you have a binary file named "data.txt", rename it:
mv data.txt data.bin
workspace files upload data.bin --path /data.bin --expire 1440

Command Not Found

Error: workspace: command not found

Solution: Install globally:

npm install -g @startanaicompany/workspace

Or use npx:

npx @startanaicompany/workspace files list

Authentication Errors

Error: 401 Unauthorized

Solution:

Verify API key is correct
Check for extra spaces in environment variable
Contact workspace administrator for valid API key

# Check current value
echo $WORKSPACE_API_KEY

# Remove and re-export (ensure no trailing spaces)
unset WORKSPACE_API_KEY
export WORKSPACE_API_KEY="your-api-key"

JSON Parse Errors (Test Case Steps)

Error: Invalid JSON for --steps

Solution: Ensure JSON is properly formatted and escaped:

# Use single quotes around JSON
workspace test-cases create "Test" \
  --project proj \
  --steps '[{"step_number":1,"description":"Step 1","expected_result":"Result 1"}]'

# Or escape double quotes
workspace test-cases create "Test" \
  --project proj \
  --steps "[{\"step_number\":1,\"description\":\"Step 1\"}]"

Support

API Endpoint: https://workspace.startanaicompany.com
GitHub Repository: https://github.com/startanaicompany/workspace
Issues: https://github.com/startanaicompany/workspace/issues
Documentation: Run workspace manual for full documentation

Version History

v1.12.1 (2026-02-18)

New: 500-word minimum validation for KB article content (consistent with other entities)
New: 20-word minimum validation for KB article summary (ensures useful context)
New: KB articles now displayed in bug/feature/ticket/test-case GET commands
Improved: Summary is now required (not optional) for KB articles
Improved: When viewing bugs/features/tickets/test-cases, linked KB articles show summary with article number
Improved: Agents can quickly see if KB article is relevant without fetching full content
Improved: Better documentation with validation requirements clearly stated
Fixed: KB update command now validates content (500 words) and summary (20 words) when updated

v1.12.0 (2026-02-18)

New: Complete Knowledge Base system for documentation and automated responses (9 commands)
New: workspace knowledgebase list - List KB articles with tag/project filtering (alias: kb)
New: workspace knowledgebase create - Create articles with Markdown support (minimum 2 tags required)
New: workspace knowledgebase get - Get article details with linked resources
New: workspace knowledgebase update - Update article content, tags, auto-response settings
New: workspace knowledgebase delete - Delete articles
New: workspace knowledgebase search - Full-text search with tag filtering
New: workspace knowledgebase link - Link articles to bugs, features, tickets, files, test-cases
New: workspace knowledgebase unlink - Unlink articles from resources
New: workspace knowledgebase find-by-resource - Find articles linked to specific resources
New: 9 new API methods in api.js for KB operations
Improved: Tags-based organization (no categories - flat structure for AI agents)
Improved: Minimum 2 tags validation for better organization
Improved: Auto-response template support for automated ticket responses
Improved: Polymorphic linking to bugs, features, tickets, files, and test-cases
Improved: Full Markdown support for article content
Improved: Article numbering system (KB-000001 format)

v1.11.2 (2026-02-17)

Fixed: Display issues showing "by undefined" in features and files list commands
Fixed: Changed created_by_agent and created_by_agent_name to created_by (matches backend response)
Improved: Added fallback to 'N/A' if creator field is missing

v1.11.1 (2026-02-17)

CRITICAL FIX: All tickets and projects commands were broken with "function is not defined" errors
Fixed: Added missing imports for 7 new API functions (listProjects, getProject, createProject, listTickets, createTicket, respondToTicket, resolveTicket)
Impact: All commands now work correctly

v1.11.0 (2026-02-17)

New: Complete tickets system implementation (8 commands eliminated fake stubs)
New: Complete projects management implementation (4 commands)
New: workspace tickets list - List support tickets with comprehensive filters
New: workspace tickets create - Create support tickets (with 500-word validation)
New: workspace tickets respond - Add responses to tickets (internal/external)
New: workspace tickets resolve - Resolve tickets with resolution types
New: workspace projects list - List all projects with pagination
New: workspace projects get - Get project details with statistics (supports short UUIDs)
New: workspace projects create - Create new projects
New: workspace projects stats - Get detailed project statistics and metrics
New: 7 new API methods in api.js (listTickets, createTicket, respondToTicket, resolveTicket, listProjects, getProject, createProject)
Improved: Full documentation for all tickets and projects commands with examples
Improved: All commands properly call backend APIs (no more "Would..." stub messages)
Fixed: Removed duplicate executions command definitions
Note: Executions commands were already properly implemented (not stubs as initially thought)

v1.10.2 (2026-02-17)

New: 500 word minimum validation for description fields on all CREATE commands
New: Helpful error messages explaining why detailed context is important
Improved: Better quality data for AI agent collaboration
Affected: features, bugs, test-cases, tickets, roadmaps, milestones create commands

v1.10.1 (2026-02-17)

Removed: Non-functional --public flag from workspace files upload command
Removed: is_public payload logic and display indicators
Improved: Cleaner codebase without dead features that don't work
Fixed: Removed confusing documentation about public file access

v1.10.0 (2026-02-17)

New: Complete bidirectional file attachments system for all entity types
New: File attachment commands (attach, link-file, list-files, unlink-file) for bugs, features, test-cases, tickets, milestones, roadmaps
New: workspace milestones get command to view milestone details
New: Bidirectional display - entities show attached files, files show which entities use them
New: File attachments display in a

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@startanaicompany/workspace

Table of Contents

Installation

Quick Start

Configuration

Required Environment Variables

Optional Environment Variables

Setup Example

Commands Reference

Files Management

workspace files upload <local-path>

workspace files download <remote-path>

workspace files list

workspace files get <remote-path>

workspace files delete <remote-path>

workspace files update <remote-path>

File Attachments

Attachment Commands

workspace <entity> attach <entity-id> <file-path>

workspace <entity> link-file <entity-id> <file-id-or-path>

workspace <entity> list-files <entity-id>

workspace <entity> unlink-file <entity-id> <attachment-id>

Bidirectional Display

Use Cases

File Management Best Practices

Important: Description Requirements

Features Management

workspace features list

workspace features create <title>

workspace features get <feature-id>

workspace features update <feature-id>

workspace features comment <feature-id> <comment>

workspace features delete <feature-id>

Bugs Management

workspace bugs list

workspace bugs create <title>

workspace bugs get <bug-id>

workspace bugs update <bug-id>

workspace bugs comment <bug-id> <comment>

workspace bugs delete <bug-id>

Test Cases Management

workspace test-cases list

workspace test-cases create <name>

workspace test-cases get <test-case-id>

workspace test-cases update <test-case-id>

workspace test-cases delete <test-case-id>

Test Executions

workspace executions start <test-case-id>

workspace executions update-step <execution-id> <step-number>

workspace executions complete <execution-id>

workspace executions get <execution-id>

workspace executions list

Support Tickets

workspace tickets list

workspace tickets create <subject>

workspace tickets get <ticket-id>

workspace tickets update <ticket-id>

workspace tickets respond <ticket-id> <message>

workspace tickets resolve <ticket-id>

Roadmaps and Milestones

workspace roadmaps list

workspace roadmaps create <name>

workspace roadmaps get <roadmap-id>

workspace roadmaps update <roadmap-id>

workspace roadmaps delete <roadmap-id>

workspace roadmaps gantt <roadmap-id>

workspace milestones list <roadmap-id>

workspace milestones get <milestone-id>

workspace milestones create <roadmap-id> <name>

workspace milestones update <milestone-id>

workspace milestones delete <milestone-id>

workspace milestones add-item <milestone-id>

workspace milestones remove-item <milestone-id> <item-id>

Knowledge Base Management

`workspace files upload <local-path>`

`workspace files download <remote-path>`

`workspace files list`

`workspace files get <remote-path>`

`workspace files delete <remote-path>`

`workspace files update <remote-path>`

`workspace <entity> attach <entity-id> <file-path>`

`workspace <entity> link-file <entity-id> <file-id-or-path>`

`workspace <entity> list-files <entity-id>`

`workspace <entity> unlink-file <entity-id> <attachment-id>`

`workspace features list`

`workspace features create <title>`

`workspace features get <feature-id>`

`workspace features update <feature-id>`

`workspace features comment <feature-id> <comment>`

`workspace features delete <feature-id>`

`workspace bugs list`

`workspace bugs create <title>`

`workspace bugs get <bug-id>`

`workspace bugs update <bug-id>`

`workspace bugs comment <bug-id> <comment>`

`workspace bugs delete <bug-id>`

`workspace test-cases list`

`workspace test-cases create <name>`

`workspace test-cases get <test-case-id>`

`workspace test-cases update <test-case-id>`

`workspace test-cases delete <test-case-id>`

`workspace executions start <test-case-id>`

`workspace executions update-step <execution-id> <step-number>`

`workspace executions complete <execution-id>`

`workspace executions get <execution-id>`

`workspace executions list`

`workspace tickets list`

`workspace tickets create <subject>`

`workspace tickets get <ticket-id>`

`workspace tickets update <ticket-id>`

`workspace tickets respond <ticket-id> <message>`

`workspace tickets resolve <ticket-id>`

`workspace roadmaps list`

`workspace roadmaps create <name>`

`workspace roadmaps get <roadmap-id>`

`workspace roadmaps update <roadmap-id>`

`workspace roadmaps delete <roadmap-id>`

`workspace roadmaps gantt <roadmap-id>`

`workspace milestones list <roadmap-id>`

`workspace milestones get <milestone-id>`

`workspace milestones create <roadmap-id> <name>`

`workspace milestones update <milestone-id>`

`workspace milestones delete <milestone-id>`

`workspace milestones add-item <milestone-id>`

`workspace milestones remove-item <milestone-id> <item-id>`

`workspace knowledgebase list`

`workspace knowledgebase create <title>`

`workspace knowledgebase get <article-id>`

`workspace knowledgebase update <article-id>`

`workspace knowledgebase delete <article-id>`

`workspace knowledgebase search <query>`

`workspace knowledgebase link <article-id>`

`workspace knowledgebase unlink <article-id>`

`workspace knowledgebase find-by-resource <type> <resource-id>`

`workspace projects list`

`workspace projects get <project-id>`

`workspace projects create <name>`

`workspace projects stats <project-id>`