@justanalyticsapp/cli

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

Installation

# 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.

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:

# 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.

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:

# 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

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

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