npm package: @jarvis.ai.chief/jarvis-cli
Description: JARVIS CLI - Command-line interface for business automation, scripting, and fine-grained control
Author: JARVIS Team
Latest version: 1.1.0

# JARVIS CLI

Command-line interface for JARVIS - AI-powered business automation platform with scripting capabilities, cross-platform support, and fine-grained control.

## Features

- **Power User Control**: Fine-grained control over logs, errors, and JARVIS behavior
- **Business Automation**: Run agents, manage tasks, notes, reminders, and approvals
- **Cross-Platform**: Works on macOS, Linux, and Windows
- **Secure Authentication**: Uses system keychain for token storage
- **Multi-Business Support**: Switch between business contexts seamlessly
- **iPhone Integration**: HTTP bridge daemon for iOS Shortcuts
- **Scriptable**: All commands can be automated and scripted
- **Fast & Lightweight**: Minimal overhead, instant command execution

## Installation

### Quick Install (Recommended)

**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/yourorg/jarvis/main/packages/cli/scripts/install.sh | bash
```

**Windows (PowerShell):**
```powershell
iwr https://raw.githubusercontent.com/yourorg/jarvis/main/packages/cli/scripts/install.ps1 -useb | iex
```

### Homebrew (macOS)

```bash
brew tap jarvis-ai/tap
brew install jarvis-cli
```

### npm / pnpm

```bash
# npm
npm install -g @jarvis/cli

# pnpm
pnpm add -g @jarvis/cli

# yarn
yarn global add @jarvis/cli
```

### Download Pre-built Binaries

Download the latest release for your platform from [GitHub Releases](https://github.com/yourorg/jarvis/releases):

- **macOS (ARM64)**: `jarvis-v1.0.0-macos-arm64.tar.gz`
- **macOS (Intel)**: `jarvis-v1.0.0-macos-x64.tar.gz`
- **Linux (x64)**: `jarvis-v1.0.0-linux-x64.tar.gz`
- **Linux (ARM64)**: `jarvis-v1.0.0-linux-arm64.tar.gz`
- **Windows (x64)**: `jarvis-v1.0.0-windows-x64.zip`

Then extract and run the included install script:

```bash
# macOS / Linux
tar -xzf jarvis-*.tar.gz
cd jarvis-*
./install.sh

# Windows
# Extract the ZIP file, then:
.\install.ps1
```

### From Source

```bash
git clone https://github.com/your-org/jarvis.git
cd jarvis/packages/cli
pnpm install
pnpm run build
npm link
```

### Verify Installation

```bash
jarvis --version
jarvis --help
```

## Quick Start

### 1. Authentication

Login to JARVIS:

```bash
jarvis auth login
```

This opens your browser for OAuth device flow authentication. Check your authentication status:

```bash
jarvis auth status
```

### 2. Business Context

List your businesses:

```bash
jarvis business list
```

Switch to a business:

```bash
jarvis business use <business-id>
```

Or use interactive selection:

```bash
jarvis business use
```

### 3. Run an Agent

Run an agent with input:

```bash
jarvis run <agent-id> --input "Your task here"
```

Or use interactive mode:

```bash
jarvis run
```

Watch task progress in real-time:

```bash
jarvis run <agent-id> --input "Task" --watch
```

## Commands

### Authentication

```bash
jarvis auth login              # Login to JARVIS
jarvis auth status             # Check authentication status
jarvis auth logout             # Logout from JARVIS
```

### Business Management

```bash
jarvis business list           # List all businesses
jarvis b ls                    # Alias for list

jarvis business use [id]       # Switch to business context
jarvis b use                   # Interactive selection

jarvis business create         # Create new business
jarvis b create --name "My Business"

jarvis business current        # Show current business
```

### Running Agents

```bash
jarvis run [agent-id]          # Run an agent
jarvis run --input "Task"      # Provide input directly
jarvis run --watch             # Watch task progress
jarvis run --priority high     # Set task priority
jarvis run --dry-run           # Simulate without executing
```

### Task Management

```bash
jarvis tasks list              # List all tasks
jarvis t ls --status running   # Filter by status
jarvis t ls --limit 50         # Limit results

jarvis tasks get <id>          # Get task details
jarvis t get <task-id>

jarvis tasks cancel <id>       # Cancel a running task
```

### Notes

```bash
jarvis notes create            # Create a note
jarvis n add "Note text"       # Create with text
jarvis n add "Note" --tags "work,important"

jarvis notes list              # List all notes
jarvis n ls --tags work        # Filter by tags
jarvis n ls --limit 20

jarvis notes search "query"    # Search notes
jarvis notes delete <id>       # Delete a note
```

### Reminders

```bash
jarvis reminders create                    # Create reminder
jarvis r add "Call John" --date "2024-01-15T14:00:00Z"
jarvis r add "Meeting" --date "tomorrow at 3pm"

jarvis reminders list                      # List reminders
jarvis r ls --status pending

jarvis reminders cancel <id>               # Cancel reminder
```

### Approvals

```bash
jarvis approvals list          # List pending approvals
jarvis a ls

jarvis approvals approve <id>  # Approve a request
jarvis a approve <id> --comment "Looks good"

jarvis approvals reject <id>   # Reject a request
jarvis a reject <id> --reason "Insufficient budget"
```

### Configuration

```bash
jarvis config list             # Show all configuration
jarvis config get <key>        # Get a value
jarvis config set <key> <val>  # Set a value
jarvis config path             # Show config file path
```

Configuration options:
- `apiUrl`: JARVIS API URL (default: http://localhost:3000)
- `logLevel`: Log level (debug, info, warn, error)
- `outputFormat`: Output format (pretty, json, compact)
- `telemetryEnabled`: Enable telemetry (true/false)

### Health & Diagnostics

```bash
jarvis health                  # Check API health
jarvis doctor                  # Run diagnostics
```

## iPhone Integration

JARVIS CLI includes an HTTP bridge daemon that enables iPhone Shortcuts integration.

### Start the Daemon

```bash
jarvisd
```

Or specify port and host:

```bash
jarvisd --port 3939 --host 0.0.0.0
```

### Setup iPhone Shortcut

1. **Start the daemon** on your Mac: `jarvisd`
2. **Note the bridge token** displayed in the terminal
3. **Find your Mac's local IP** (shown in daemon output)
4. **Create a Shortcut** on your iPhone:
   - Action: "Get Contents of URL"
   - URL: `http://YOUR_MAC_IP:3939/run`
   - Method: POST
   - Headers:
     ```json
     {
       "Authorization": "Bearer YOUR_BRIDGE_TOKEN",
       "Content-Type": "application/json"
     }
     ```
   - Body:
     ```json
     {
       "agentId": "YOUR_AGENT_ID",
       "input": "Your task here"
     }
     ```

### Available Bridge Endpoints

```
POST   /run                    # Run an agent
GET    /tasks                  # List tasks
GET    /tasks/:id              # Get task details
POST   /notes                  # Create a note
GET    /notes                  # List notes
POST   /reminders              # Create a reminder
GET    /businesses             # List businesses
```

## Scripting Examples

### Bash Script: Auto-run Agent Daily

```bash
#!/bin/bash
# daily-report.sh

jarvis auth status || jarvis auth login
jarvis business use "my-business-id"
jarvis run "report-agent-id" --input "Generate daily report for $(date +%Y-%m-%d)"
```

### Cron Job: Check Pending Approvals

```bash
# Check approvals every hour
0 * * * * jarvis approvals list | mail -s "Pending Approvals" you@example.com
```

### Node.js Script: Automated Task Management

```javascript
import { exec } from 'child_process';
import util from 'util';

const execPromise = util.promisify(exec);

async function processTasks() {
  // Get running tasks
  const { stdout } = await execPromise('jarvis tasks list --status running --json');
  const tasks = JSON.parse(stdout);

  // Cancel long-running tasks
  const oneHourAgo = Date.now() - 3600000;
  for (const task of tasks) {
    if (new Date(task.createdAt).getTime() < oneHourAgo) {
      await execPromise(`jarvis tasks cancel ${task.id}`);
      console.log(`Cancelled task ${task.id}`);
    }
  }
}

processTasks();
```

### Python Script: Bulk Note Creation

```python
import subprocess
import json

notes = [
    {"text": "Review Q4 metrics", "tags": ["work", "quarterly"]},
    {"text": "Prepare presentation", "tags": ["work", "urgent"]},
    {"text": "Schedule team meeting", "tags": ["work", "admin"]}
]

for note in notes:
    tags = ",".join(note["tags"])
    subprocess.run([
        "jarvis", "notes", "create",
        note["text"],
        "--tags", tags
    ])
```

## Advanced Usage

### Debug Mode

Enable verbose logging:

```bash
jarvis --debug tasks list
```

Or set it permanently:

```bash
jarvis config set logLevel debug
```

### JSON Output

Get JSON output for scripting:

```bash
jarvis --json tasks list
```

### Environment Variables

```bash
export JARVIS_API_URL=https://api.jarvis.com
export JARVIS_TELEMETRY_URL=https://telemetry.jarvis.com
```

## Configuration File

JARVIS CLI stores configuration in `~/.jarvis/config.json`:

```json
{
  "apiUrl": "http://localhost:3000",
  "currentBusinessId": "clx...",
  "currentBusinessSlug": "my-business",
  "bridgeToken": "abc123...",
  "telemetryEnabled": false,
  "logLevel": "info",
  "outputFormat": "pretty"
}
```

## Security

- **Keychain Storage**: Access tokens stored in system keychain (macOS Keychain, Windows Credential Manager)
- **Auto-Refresh**: Tokens automatically refreshed before expiration
- **Bridge Token**: Unique token for iPhone integration, regenerated on demand
- **Secure Config**: Config file permissions set to 0600 (owner read/write only)

## Troubleshooting

### Authentication Issues

```bash
# Check authentication status
jarvis auth status

# Re-login if token expired
jarvis auth logout
jarvis auth login
```

### Connection Issues

```bash
# Check API health
jarvis health

# Run full diagnostics
jarvis doctor

# Check configuration
jarvis config list
```

### Business Context Issues

```bash
# Verify current business
jarvis business current

# Re-select business
jarvis business use
```

## Development

### Building from Source

```bash
pnpm install
pnpm run build
```

### Running Tests

```bash
pnpm test
pnpm test:watch
pnpm test:coverage
```

### Linting & Formatting

```bash
pnpm lint
pnpm format
```

### Creating Binaries

```bash
# Build everything (clean → bundle → binaries → installers)
pnpm run package

# Or step by step:
pnpm run build          # TypeScript compilation
pnpm run build:bundle   # Create optimized bundles with esbuild
pnpm run build:binaries # Create platform-specific binaries with pkg
pnpm run build:installers # Package into distributable archives
```

This creates standalone binaries in `build/binaries/` for:
- macOS (Intel & Apple Silicon)
- Linux (x64 & ARM64)
- Windows (x64)

And distributable packages in `build/dist/`:
- `jarvis-v{version}-macos-arm64.tar.gz`
- `jarvis-v{version}-macos-x64.tar.gz`
- `jarvis-v{version}-linux-x64.tar.gz`
- `jarvis-v{version}-linux-arm64.tar.gz`
- `jarvis-v{version}-windows-x64.zip`
- `checksums.txt` (SHA-256 hashes)

See [DISTRIBUTION.md](./DISTRIBUTION.md) for detailed build and release documentation.

## Support

- **Documentation**: https://docs.jarvis.com/cli
- **Issues**: https://github.com/your-org/jarvis/issues
- **Discussions**: https://github.com/your-org/jarvis/discussions

## License

MIT License - see LICENSE file for details