npm package: @justanalyticsapp/cli
Description: JustAnalytics CLI - Upload source maps and manage releases from CI/CD pipelines
Latest version: 0.1.1

# @justanalyticsapp/cli

Command-line tool for uploading source maps and managing releases from CI/CD pipelines.

## Installation

```bash
# Use directly with npx (no install required)
npx @justanalyticsapp/cli --help

# Or install globally
npm install -g @justanalyticsapp/cli
```

**Requires Node.js 18 or later.**

## Authentication

The CLI requires a JustAnalytics API key. You can provide it in two ways:

1. **Flag:** `--api-key ja_sk_your_key_here`
2. **Environment variable:** `JUSTANALYTICS_API_KEY=ja_sk_your_key_here`

The flag takes precedence over the environment variable.

You can generate an API key from **Settings > API Keys** in the JustAnalytics dashboard.

## Commands

### `sourcemaps upload`

Upload source map files for a release. This enables deobfuscation of minified stack traces in error reports.

```bash
justanalytics sourcemaps upload [options] <files...>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `files` | Source map files or glob patterns (e.g., `dist/**/*.map`) |

**Options:**

| Option | Description | Required |
|--------|-------------|----------|
| `--release <version>` | Release version to associate source maps with | Yes |
| `--site-id <id>` | JustAnalytics site ID | Yes |
| `--url-prefix <prefix>` | URL prefix to prepend to file names (e.g., `~/static/js/`) | No |

**Examples:**

```bash
# Upload all .map files from dist/
justanalytics sourcemaps upload --release v1.2.3 --site-id abc123 dist/**/*.map

# Upload with a URL prefix
justanalytics sourcemaps upload --release v1.2.3 --site-id abc123 --url-prefix ~/static/js/ build/*.map
```

**Output:**

```
Uploading source maps for release "v1.2.3"...

  Uploading [1/3] main.abc123.js.map ... OK (142 KB)
  Uploading [2/3] vendor.def456.js.map ... OK (891 KB)
  Uploading [3/3] polyfills.ghi789.js.map ... OK (23 KB)

Successfully uploaded 3 source maps for release "v1.2.3" (0 failed)
```

### `releases new`

Register a new release deployment. This enables release tracking and regression detection in the JustAnalytics dashboard.

```bash
justanalytics releases new [options]
```

**Options:**

| Option | Description | Required |
|--------|-------------|----------|
| `--version <version>` | Release version | Yes |
| `--environment <env>` | Deployment environment (default: `production`) | No |
| `--commit <sha>` | Git commit SHA | No |
| `--commit-message <message>` | Git commit message | No |
| `--repository-url <url>` | Repository URL | No |
| `--deployed-by <name>` | Who or what triggered the deploy | No |

**Examples:**

```bash
# Register a basic release
justanalytics releases new --version v1.2.3

# Register a release with full metadata
justanalytics releases new \
  --version v1.2.3 \
  --environment production \
  --commit abc123def456 \
  --commit-message "fix: resolve cart total rounding" \
  --repository-url https://github.com/org/repo \
  --deployed-by "github-actions"
```

**Output:**

```
Release "v1.2.3" created for environment "production" (id: rel_xyz789)
```

## Global Options

| Option | Description |
|--------|-------------|
| `--api-key <key>` | API key (or set `JUSTANALYTICS_API_KEY` env var) |
| `--api-url <url>` | API base URL (default: `https://justanalytics.tech`) |
| `-V, --version` | Output the version number |
| `-h, --help` | Display help for command |

## CI/CD Integration

### GitHub Actions

```yaml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npm run build

      # Upload source maps
      - name: Upload source maps
        run: npx @justanalyticsapp/cli sourcemaps upload --release ${{ github.sha }} --site-id ${{ vars.JUSTANALYTICS_SITE_ID }} dist/**/*.map
        env:
          JUSTANALYTICS_API_KEY: ${{ secrets.JUSTANALYTICS_API_KEY }}

      # Register the release
      - name: Register release
        run: |
          npx @justanalyticsapp/cli releases new \
            --version ${{ github.sha }} \
            --environment production \
            --commit ${{ github.sha }} \
            --commit-message "${{ github.event.head_commit.message }}" \
            --repository-url ${{ github.server_url }}/${{ github.repository }} \
            --deployed-by "github-actions"
        env:
          JUSTANALYTICS_API_KEY: ${{ secrets.JUSTANALYTICS_API_KEY }}
```

### GitLab CI

```yaml
stages:
  - build
  - deploy

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  image: node:20
  script:
    # Upload source maps
    - npx @justanalyticsapp/cli sourcemaps upload --release $CI_COMMIT_SHA --site-id $JUSTANALYTICS_SITE_ID dist/**/*.map

    # Register the release
    - >
      npx @justanalyticsapp/cli releases new
      --version $CI_COMMIT_SHA
      --environment production
      --commit $CI_COMMIT_SHA
      --commit-message "$CI_COMMIT_MESSAGE"
      --repository-url $CI_PROJECT_URL
      --deployed-by "gitlab-ci"
  variables:
    JUSTANALYTICS_API_KEY: $JUSTANALYTICS_API_KEY
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All operations succeeded |
| 1 | Validation error, authentication failure, or one or more operations failed |

## File Size Limit

Source map files larger than 50MB are automatically skipped with a warning. The server also enforces this limit.

## Color Output

The CLI uses colored output (green for success, red for errors, yellow for warnings). Colors are automatically disabled when:

- The `NO_COLOR` environment variable is set (any value)
- stdout is not a TTY (e.g., piped output)

## License

MIT