qamax-auth-cli

QualityMax Auth Capture CLI

CLI tool to capture authentication sessions for QualityMax AI crawling.

Installation

One-line Install (macOS/Linux)

curl https://github.com/Quality-Max/qamax-rag-app/releases/latest/download/install.sh | sh

This installs the CLI to /usr/local/lib/qamax and creates a symlink at /usr/local/bin/qamax-auth.

Manual Download

Download the appropriate binary from GitHub Releases:

Platform	File
macOS (Intel)	qamax-auth-darwin-x64.tar.gz
macOS (Apple Silicon)	qamax-auth-darwin-arm64.tar.gz
Linux (x64)	qamax-auth-linux-x64.tar.gz
Windows (x64)	qamax-auth-win-x64.zip

Uninstall

curl https://github.com/Quality-Max/qamax-rag-app/releases/latest/download/uninstall.sh | sh

Usage

Login

Authenticate with your QualityMax account:

qamax-auth login

List Projects

qamax-auth projects

Capture Authentication

Open a browser, log into your app, then save the session:

qamax-auth capture https://myapp.com -p PROJECT_ID -n "Profile Name"

Options:

• -p, --project <id> - Project ID (required)
• -n, --name <name> - Auth profile name (required)
• -t, --timeout <ms> - Browser timeout (default: 300000)

Example Workflow

# 1. Login to QualityMax
qamax-auth login

# 2. List your projects
qamax-auth projects

# 3. Capture auth for staging environment
qamax-auth capture https://staging.myapp.com -p 42 -n "staging-auth"

# 4. Now run AI crawl with authentication
#    (via QualityMax web UI, select the auth profile)

How It Works

• Opens Chrome with remote debugging enabled
• You log into your application manually
• CLI captures cookies, localStorage, and session storage
• Encrypts and uploads as an "Auth Profile" to QualityMax
• AI crawl uses this profile to authenticate before crawling

Development

Prerequisites

• Node.js 18+
• Chrome browser installed

Run from Source

cd tools/auth-capture-cli
npm install
node index.js login

Build Standalone Binaries

npm run build

Outputs tarballs to dist/:

• qamax-auth-vX.X.X-darwin-x64.tar.gz
• qamax-auth-vX.X.X-darwin-arm64.tar.gz
• qamax-auth-vX.X.X-linux-x64.tar.gz
• qamax-auth-vX.X.X-win-x64.zip

Release Process

• Update version in package.json
• Commit changes
• Create and push a git tag:

  git tag v1.0.0
  git push origin v1.0.0
  

• GitHub Actions automatically builds and publishes to Releases

Architecture

tools/auth-capture-cli/
├── index.js              # CLI entry point (Commander.js)
├── lib/
│   ├── api.js            # QualityMax API client
│   ├── auth.js           # Login/token management
│   ├── browser.js        # Chrome launcher + CDP
│   └── config.js         # Config file (~/.qamax/config.json)
├── scripts/
│   ├── build.sh          # Build standalone binaries
│   ├── install.sh        # User install script
│   └── uninstall.sh      # User uninstall script
├── .github/workflows/
│   └── release.yml       # Auto-build on git tag
└── package.json

Troubleshooting

"Chrome not found"

Install Chrome or set the path:

export CHROME_PATH=/path/to/chrome

"Permission denied" on install

The install script requires sudo:

sudo bash -c "curl ... | sh"

Session not working in AI crawl

• Ensure you completed the full login flow before closing the browser
• Check if the session has expired (some sites have short session timeouts)
• Try capturing again with a fresh login