CLI Documentation

Installation

Prerequisites

• Node.js 18+ — check with node -v
• macOS or Linux — Windows support via WSL
• Git — your project must be a git repository

One-liner install

curl -fsSL https://qualitygraph.harnessqa.dev/cli-dist/install.sh | bash

This downloads the CLI bundle and installs it to ~/.qualitygraph/bin/qg. It also adds the directory to your PATH in your shell config.

After installation

Reload your shell or source your config to use qg immediately:

source ~/.zshrc    # or ~/.bashrc

Verify it works:

qg --version

Manual install

If you prefer not to pipe curl to bash:

# Download the bundle
curl -o ~/.qualitygraph/bin/qg-bundle.js https://qualitygraph.harnessqa.dev/cli-dist/qg-bundle.js
mkdir -p ~/.qualitygraph/bin

# Create wrapper script
cat > ~/.qualitygraph/bin/qg <<'EOF'
#!/usr/bin/env node
require('./qg-bundle.js');
EOF
chmod +x ~/.qualitygraph/bin/qg

# Add to PATH
export PATH="$HOME/.qualitygraph/bin:$PATH"

Uninstall

rm -rf ~/.qualitygraph
# Then remove the PATH line from your ~/.zshrc or ~/.bashrc

Authentication

You need a QualityGraph account to upload analysis results. Create one at qualitygraph.harnessqa.dev/login or use the login command directly (it will register you automatically if you don't have an account).

Login

qg login -e you@company.com -p your-password

Check status

qg status

Logged in as: you@company.com
Server: https://qualitygraph.harnessqa.dev

Logout

qg logout

Analyzing Repositories

Basic usage

Navigate to any git repository and run:

cd /path/to/your/project
qg analyze

The CLI does two things. It scans the source tree, identifies test files, classifies them by layer (unit, API, integration, UI, E2E, contract) and estimates which production files have a test. And it looks for coverage reports a test run left behind (coverage/lcov.info, coverage.xml, jacoco.xml) and uploads those as measured coverage, with per-file and per-line detail. A measurement always outranks the estimate for its layer.

Example output

$ qg analyze

Analyzing myorg/backend-api...

Scanned 1,204 files

  myorg/backend-api
  ────────────────────────────────────────────────────────────
  Test Type       Coverage   Files        Test Files   Lines
  ────────────────────────────────────────────────────────────
  UNIT            42.30% [████░░░░░░]   89/ 210       94     18240/ 43120
  API              8.10% [█░░░░░░░░░]   17/ 210       12      3499/ 43120
  INTEGRATION      3.33% [░░░░░░░░░░]    7/ 210        5      1438/ 43120
  E2E              1.90% [░░░░░░░░░░]    4/ 210        8       820/ 43120
  ────────────────────────────────────────────────────────────

  Coverage reports found (1):
    lcov      coverage/lcov.info  (184.2 KB)
  These measure what the tests ran; they replace the file-layout estimate for their layer.

Uploading to https://qualitygraph.harnessqa.dev...
Uploaded! Repository: a1b2c3d4-...
View at: https://qualitygraph.harnessqa.dev
Uploading coverage/lcov.info as UNIT coverage (lcov)... 71.4% of 43120 lines, 210 files

Run the tests first

The measured numbers come from your own test runner, so run it with coverage on before qg analyze:

npx jest --coverage                 # writes coverage/lcov.info
pytest --cov=src --cov-report=xml   # writes coverage.xml
./gradlew test jacocoTestReport     # writes build/reports/jacoco/test/jacocoTestReport.xml
qg analyze

Reports are filed under the layer given by --report-type (default UNIT). To upload a specific file, or reports for several layers, use qg coverage upload:

qg coverage upload coverage/lcov.info --type UNIT
qg coverage upload reports/api-coverage.xml --type API --format cobertura
qg analyze --no-reports             # estimate only, skip report discovery

Local-only mode

Run the analysis without uploading results — useful for previewing before pushing, or for repos you don't want tracked:

qg analyze --local

Analyze a different directory

qg analyze -d /path/to/other-repo

How the estimate is calculated

Command Reference

Test Detection

The CLI identifies test files by their naming conventions and directory structure, then classifies them into five test types:

Supported Languages

The CLI recognizes source and test files in the following languages:

Configuration

All CLI configuration is stored in ~/.qualitygraph/config.json.

Config file format

{
  "server": "https://qualitygraph.harnessqa.dev",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "email": "you@company.com"
}

File structure

~/.qualitygraph/
├── bin/
│   ├── qg              # CLI wrapper script
│   └── qg-bundle.js    # Bundled CLI (122KB)
└── config.json          # Auth credentials (mode 0600)

Custom server

For self-hosted QualityGraph instances, pass the -s flag:

qg login -e you@company.com -p pass -s https://qg.internal.company.com

CI/CD Integration

Run QualityGraph analysis automatically in your CI pipeline to track coverage over time.

GitHub Actions

name: QualityGraph Analysis

on:
  push:
    branches: [main]
  pull_request:

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install QualityGraph CLI
        run: curl -fsSL https://qualitygraph.harnessqa.dev/cli-dist/install.sh | bash

      - name: Login & analyze
        run: |
          export PATH="$HOME/.qualitygraph/bin:$PATH"
          qg login -e ${{ secrets.QG_EMAIL }} -p ${{ secrets.QG_PASSWORD }}
          qg analyze

GitLab CI

qualitygraph:
  image: node:20
  stage: test
  script:
    - curl -fsSL https://qualitygraph.harnessqa.dev/cli-dist/install.sh | bash
    - export PATH="$HOME/.qualitygraph/bin:$PATH"
    - qg login -e $QG_EMAIL -p $QG_PASSWORD
    - qg analyze
  only:
    - main

Troubleshooting

source ~/.zshrc    # or ~/.bashrc

qg analyze -d /path/to/repo

qg login -e you@company.com -p your-password

qg analyze --local

qg login -e you@company.com -p your-password

FAQ