npm package: @nuvuli/spinner
Description: Node.js port of the Go spinner service for AI orchestration
Author: Nuvuli
Latest version: 0.0.11

# @nuvuli/spinner

An AI task orchestration service that connects to the Nuvuli Spinner Platform to execute AI-powered tasks on your local machine.

## Installation

Install globally via npm:

```bash
npm install -g @nuvuli/spinner
```

## Usage

After installation, you can run the spinner from anywhere:

```bash
spinner
```

### Command Line Options

```bash
spinner [config-file] [options]

Arguments:
  config-file     Path to YAML configuration file (default: spinner.yaml)

Options:
  -h, --help      Show help message
  -v, --version   Show version information

Examples:
  spinner                           # Use default spinner.yaml config
  spinner /path/to/config.yaml      # Use specific config file
  spinner --help                    # Show help
```

## Configuration

Create a `spinner.yaml` file in your working directory:

```yaml
api_url: https://your-nuvuli-api-url.com
api_key: your-api-key-here                      # Get this from inside the Spinner UI.
# spinner_id will be auto-generated on first run

# Optional AI provider API keys (can also be set via Nuvuli dashboard)
anthropic_key: your-anthropic-key
openai_key: your-openai-key
mistral_key: your-mistral-key

# Optional Claude CLI configuration
claude_path: /usr/local/bin/claude
claude_allowed_tools: ["read", "write"]
claude_disallowed_tools: ["bash"]
claude_mcp_config_path: ~/.claude/mcp.json
```

## Getting Started

1. **Install**: `npm install -g @nuvuli/spinner`
2. **Configure**: Create a `spinner.yaml` file with your API settings
3. **Run**: Execute `spinner` in your terminal
4. **Authorize**: The first run will register your spinner and wait for authorization
5. **Use**: Once authorized, the spinner will connect to Nuvuli and execute assigned tasks

## Features

- **Multi-AI Provider Support**: Works with Claude, OpenAI, Mistral, and more
- **Real-time Task Execution**: Connects via WebSocket for instant task processing
- **Automatic Registration**: Self-registers with the Nuvuli platform
- **Graceful Shutdown**: Handles SIGINT/SIGTERM for clean exits
- **Reconnection Logic**: Automatically reconnects if connection is lost
- **System Integration**: Reports system information for optimal task routing

## Troubleshooting

### Common Issues

1. **"Failed to load configuration"**
   - Ensure `spinner.yaml` exists in the current directory
   - Check YAML syntax is valid
   - Verify `api_url` and `api_key` are present

2. **"Failed to verify API key"**
   - Check Nuvuli platform is accessible
   - Verify API key is valid and not expired
   - Ensure network connectivity

3. **"Authorization timeout"**
   - Log into the Nuvuli UI and authorize the spinner manually
   - Check spinner appears in the spinners list
   - Try running again after authorization

### Getting Help

If you encounter issues:
1. Run `spinner --help` for usage information
2. Check your configuration file syntax
3. Verify network connectivity to the Nuvuli platform
4. Contact support if problems persist

## Requirements

- Node.js 18.0.0 or higher
- Active Nuvuli account with API access
- Network connectivity to Nuvuli platform

## Support

For issues and documentation, visit: https://nuvuli.com/spinner