CLI Usage

LensCore CLI is a powerful command-line interface for accessibility testing and web crawling. It provides comprehensive tools to analyze websites for accessibility compliance, crawl web pages, and generate detailed reports.

Installation

LensCore CLI is published as the @accesstime/lenscore npm package and requires Node.js 20+.

bash

# Global install (recommended)
npm install -g @accesstime/lenscore

# Or run without global install
npx @accesstime/lenscore --help

After a global install the CLI is available everywhere as the lens-core command.

Quick Start Guide

1. Setup LensCore

bash

lens-core setup --port 3009

2. Build and Start Services

bash

lens-core build

3. Check Service Status

bash

lens-core status

4. Test a Single Page

bash

lens-core test https://example.com

5. Crawl a Website

bash

lens-core crawl https://example.com

6. Full Website Scan

bash

lens-core scan https://example.com

Note

After setup, you can either run lens-core build (which builds and starts services) or lens-core up (which only starts services). Use lens-core status to check if services are running properly.

Commands Overview

Setup & Configuration

`setup [options]`

Setup LensCore configuration and Docker environment.

bash

# Interactive setup
lens-core setup

Options:

--port <port>: Set API port (default: 3001)
-u, --url <url>: Set custom base URL (e.g., http://localhost:3003)
--ai: Enable AI features during setup
-k, --openai-key <key>: Set OpenAI API key

`config [options]`

Manage LensCore configuration settings.

Options:

-s, --set <key=value>: Set configuration value (e.g., docker.port=3003)
-g, --get <key>: Get configuration value (e.g., docker.port)
-l, --list: List all configuration settings

Examples:

bash

# List all configuration
lens-core config --list

# Get specific configuration value
lens-core config --get docker.port

# Set configuration value
lens-core config --set "docker.port=3009"

# Set OpenAI API key
lens-core config --set "openai.apiKey=your-key-here"

Accessibility Testing

`test [options] <url>`

Test accessibility of a single page.

Options:

--enable-ai: Enable AI-powered analysis
-k, --openai-key <key>: OpenAI API key
-c, --project-context <context>: Project context (e.g., "react,tailwind")
-w, --web: Generate HTML report
-t, --timeout <ms>: Page load timeout (default: 30000)
-r, --rules <rules>: Specific rules to test (comma-separated)
-g, --tags <tags>: WCAG tags to test (e.g., "wcag2a,wcag2aa")
--no-screenshot: Skip screenshot capture
--skip-cache: Bypass cache and force a fresh test

Examples:

bash

lens-core test https://example.com
lens-core test https://example.com --enable-ai
lens-core test https://example.com --timeout 30000
lens-core test https://example.com --rules "color-contrast,keyboard"
lens-core test https://example.com --project-context "react,tailwind"
lens-core test https://example.com --web
lens-core test https://example.com --no-screenshot

`test-multiple [options] <urls...>`

Test accessibility of multiple pages simultaneously.

Examples:

bash

lens-core test-multiple https://example.com https://google.com
lens-core test-multiple https://example.com https://google.com --enable-ai
lens-core test-multiple https://example.com https://google.com --web

Web Crawling

`crawl [options] <url>`

Crawl website and discover pages.

Options:

-w, --web: Generate HTML report
-u, --max-urls <number>: Maximum URLs to crawl
-d, --max-depth <number>: Maximum crawl depth
-t, --timeout <ms>: Page load timeout
-j, --concurrency <number>: Concurrent requests
-l, --wait-until <event>: Wait until event (load|domcontentloaded|networkidle)
--skip-cache: Bypass cache and force a fresh crawl

Examples:

bash

lens-core crawl https://example.com
lens-core crawl https://example.com --max-urls 50 --max-depth 3
lens-core crawl https://example.com --concurrency 5
lens-core crawl https://example.com --web

`scan [options] <url>`

Crawl website and test accessibility (combined operation).

Examples:

bash

lens-core scan https://example.com
lens-core scan https://example.com --enable-ai
lens-core scan https://example.com --max-urls 50 --max-depth 3
lens-core scan https://example.com --project-context "react,tailwind"
lens-core scan https://example.com --web

Options (summary):

All crawl options: --max-urls, --max-depth, --timeout, --concurrency, --wait-until, --skip-cache
All test options: --enable-ai, --openai-key, --project-context, --web, --timeout, --rules, --tags, --no-screenshot

Docker Management

`build`

Build Docker image and start containers.

bash

lens-core build

`up`

Start Docker containers (without building).

bash

lens-core up

`down`

Stop and remove Docker containers.

bash

lens-core down

`status`

Check Docker container and API status.

bash

lens-core status

`health`

Check API health endpoint.

bash

lens-core health

Cache Management

`cache:clear`

Clear all cached data used by LensCore (in-memory or external cache depending on your configuration).

bash

lens-core cache:clear

`cache:stats`

Show cache statistics such as hit rate and cache size.

bash

lens-core cache:stats

Output Formats

JSON Output (Default)

bash

lens-core test https://example.com

Returns JSON with:

Test results
Violations
Passes
Incomplete tests
Screenshots (base64)

Web Output (HTML Report)

bash

lens-core test https://example.com --web

Generates an HTML report saved to web/output/ directory with:

Visual representation
Detailed violation descriptions
Screenshot previews
Code snippets
Recommendations

Configuration File

LensCore configuration is stored in ~/.lenscore/config.json:

json

{
  "mode": "local",
  "docker": {
    "image": "lenscore:latest",
    "port": 3001
  },
  "remote": {
    "baseUrl": "http://localhost:3001"
  },
  "openai": {
    "apiKey": "",
    "model": "gpt-3.5-turbo",
    "enabled": false
  },
  "project": {
    "framework": "",
    "cssFramework": "",
    "language": "",
    "buildTool": ""
  }
}

Environment Variables

LENSCORE_PORT: API server port
OPENAI_API_KEY: OpenAI API key
CACHE_TYPE: Cache type (memory|redis|none)
CACHE_TTL: Cache time-to-live (seconds)
CACHE_MAX_SIZE: Maximum cache size

Real-World Examples

Complete Website Analysis

bash

lens-core setup --ai --openai-key your-api-key
lens-core build
lens-core health
lens-core scan https://example.com --max-urls 50 --enable-ai --web

Batch Testing

bash

lens-core test-multiple \
  https://example.com \
  https://example.com/about \
  https://example.com/contact \
  --enable-ai \
  --project-context "react,tailwind" \
  --web

Custom Crawling

bash

lens-core crawl https://example.com \
  --max-urls 50 \
  --max-depth 3 \
  --concurrency 5 \
  --wait-until networkidle \
  --web

CI/CD Integration

bash

lens-core setup --port 3001 --ai --openai-key $OPENAI_API_KEY
lens-core build
lens-core health
lens-core test https://example.com > results.json

CI & Release Workflow

This section is intended for contributors and maintainers who work on the LensCore CLI itself.

Continuous Integration (GitHub Actions)

On every push to main and for all pull requests, GitHub Actions runs:

Build Check (.github/workflows/build.yml): npm run typecheck and npm run build
Test Check (.github/workflows/test.yml): npm run test and npm run test:coverage
Lint Check (.github/workflows/lint.yml): npm run lint and npm run format:check

In addition, the Security Check workflow (.github/workflows/security.yml) runs on a schedule to:

Perform npm audit with a moderate severity threshold
Generate reports about outdated dependencies

Documentation Deployment

Documentation is built and deployed to GitHub Pages by .github/workflows/deploy-docs.yml:

Triggered on pushes to main that touch docs/**, package.json, package-lock.json, or the workflow itself
Runs npm ci and npm run docs:build
Publishes the built docs to GitHub Pages

Releasing a New CLI Version to npm

Releases of the @accesstime/lenscore npm package are currently performed manually, outside of CI. A typical release flow is:

Ensure the main branch is green
- All GitHub Actions workflows (build, test, lint, security) should be passing.
Update the version
- Use npm version patch|minor|major (preferred) or edit package.json manually.
- This updates the version field and creates a Git tag when using npm version.
Build the project
- Run npm run build to generate the dist/ output, including dist/cli.js used by bin/index.js.
Publish to npm
- Log in with npm login (once per environment).
- For an existing public package: npm publish
- For the first publish of the scoped package: npm publish --access public
Verify the new version
- Install globally on a clean environment: npm install -g @accesstime/lenscore
- Run lens-core --version to confirm the published version.

Troubleshooting

Common Issues

bash

# Docker not running
docker info
lens-core up

# Port conflicts
lens-core setup --port 3002

# Permission issues
ls -la ~/.lenscore/
lens-core config --reset

Getting Help

Use lens-core --help for command list
Use lens-core help <command> for specific command help
Check lens-core status for service health
Review logs in ~/.lenscore/logs/

Advanced Usage

Custom Rules

Test specific accessibility rules:

bash

lens-core test https://example.com --rules "color-contrast,keyboard"
lens-core test https://example.com --tags "wcag2a,wcag2aa"

Performance Tuning

Optimize crawling performance:

bash

lens-core scan https://example.com \
  --concurrency 5 \
  --timeout 30000 \
  --max-urls 50 \
  --max-depth 3

Integration Examples

Node.js Integration

javascript

const { exec } = require('child_process');

exec('lens-core test https://example.com', (error, stdout, stderr) => {
  if (error) {
    console.error(`Error: ${error.message}`);
    return;
  }
  const results = JSON.parse(stdout);
  console.log(`Found ${results.violations.length} violations`);
});

Shell Script Integration

bash

#!/bin/bash
# test-suite.sh

lens-core health || exit 1

lens-core test https://example.com > results.json
if [ $(jq '.violations | length' results.json) -gt 0 ]; then
  echo "Accessibility violations found!"
  exit 1
fi

Support

GitHub Repository: https://github.com/Access-Time/LensCore
Issue Tracker: https://github.com/Access-Time/LensCore/issues
Documentation: https://accesstime.github.io/LensCore

For more information about specific features, check out:

API Reference - RESTful API documentation
Accessibility Guide - WCAG compliance information
Contributing Guide - How to contribute to LensCore

CLI Usage ​

Installation ​

Quick Start Guide ​

1. Setup LensCore ​

2. Build and Start Services ​

3. Check Service Status ​

4. Test a Single Page ​

5. Crawl a Website ​

6. Full Website Scan ​

Commands Overview ​

Setup & Configuration ​

setup [options] ​

config [options] ​

Accessibility Testing ​

test [options] <url> ​

test-multiple [options] <urls...> ​

Web Crawling ​

crawl [options] <url> ​

scan [options] <url> ​

Docker Management ​

build ​

up ​

down ​

status ​

health ​

Cache Management ​

cache:clear ​

cache:stats ​

Output Formats ​

JSON Output (Default) ​

Web Output (HTML Report) ​

Configuration File ​

Environment Variables ​

Real-World Examples ​

Complete Website Analysis ​

Batch Testing ​

Custom Crawling ​

CI/CD Integration ​

CI & Release Workflow ​

Continuous Integration (GitHub Actions) ​

Documentation Deployment ​

Releasing a New CLI Version to npm ​

Troubleshooting ​

Common Issues ​

Getting Help ​

Advanced Usage ​

Custom Rules ​

Performance Tuning ​

Integration Examples ​

Node.js Integration ​

Shell Script Integration ​

Support ​

CLI Usage

Installation

Quick Start Guide

1. Setup LensCore

2. Build and Start Services

3. Check Service Status

4. Test a Single Page

5. Crawl a Website

6. Full Website Scan

Commands Overview

Setup & Configuration

`setup [options]`

`config [options]`

Accessibility Testing

`test [options] <url>`

`test-multiple [options] <urls...>`

Web Crawling

`crawl [options] <url>`

`scan [options] <url>`

Docker Management

`build`

`up`

`down`

`status`

`health`

Cache Management

`cache:clear`

`cache:stats`

Output Formats

JSON Output (Default)

Web Output (HTML Report)

Configuration File

Environment Variables

Real-World Examples

Complete Website Analysis

Batch Testing

Custom Crawling

CI/CD Integration

CI & Release Workflow

Continuous Integration (GitHub Actions)

Documentation Deployment

Releasing a New CLI Version to npm

Troubleshooting

Common Issues

Getting Help

Advanced Usage

Custom Rules

Performance Tuning

Integration Examples

Node.js Integration

Shell Script Integration

Support