CLI Reference

Install and discover commands

The published @aelira/[email protected] package requires Node.js 22 or newer. From your project directory, install it locally with Bun, then expose the local command binaries for this shell:

bun add --dev @aelira/[email protected]
export PATH="$PWD/node_modules/.bin:$PATH"
aelira --version
aelira --help
aelira scan pdf --help
aelira ci --help

Check that the version output contains @aelira/cli/0.9.11. Commit the package manifest and lockfile to reproduce the dependency resolution in CI. The CLI is MIT licensed.

Local browser checks (aelira scan and aelira ci) use Playwright and need its Chromium browser. After installing the package, use the project's Playwright binary:

playwright install chromium
# Linux CI runners that also need operating-system browser dependencies:
# playwright install --with-deps chromium

Browser installation downloads Chromium; the Linux dependency option may require administrator permissions. Server-backed PDF commands do not need a local browser.

Connect to your API

Document scans, history and remediation use a running Aelira API and worker. Set the API origin, then use the interactive login and choose to paste an existing API key:

aelira config set api-url http://localhost:8000
aelira auth login
aelira config show
aelira config validate

Use your deployment's HTTPS API origin in production. config validate checks API health; it does not prove your key can access a specific scan. In automation, supply AELIRA_API_KEY from CI secrets and set AELIRA_API_URL to the API origin. The shared API client sends the bearer header.

For commands accepting --api-url, resolution is: explicit flag → AELIRA_API_URL → active profile → http://localhost:8000. AELIRA_API_KEY overrides the active profile's key. AELIRA_DEPARTMENT overrides the stored department. Configuration lives in ~/.aelira/config.json, or in AELIRA_CONFIG_DIR when set.

aelira config profile create staging --api-url https://api.example.edu
aelira config profile use staging
aelira auth login
aelira config profile list

Replace the example origin with your server. Login stores the key in the active profile. Selecting an API URL for a single command does not save it for future commands; set the profile URL first. Protect the configuration file as a credential file. Environment overrides still apply after switching profiles or logging out.

Scan documents and keep the result

# Single PDF: upload, poll progress, then retrieve completed details
aelira scan pdf document.pdf --format json --output pdf-result.json

# Recursively scan PDFs in a directory
aelira scan pdf ./course-materials/ --format json --output pdf-batch.json

# Discover the format-specific commands
aelira scan ppt --help
aelira scan docx --help
aelira scan xlsx --help
aelira scan latex --help

The PDF command polls at roughly two-second intervals with a 120-second polling timeout, separate from upload and HTTP request timeouts. It retrieves the API detail envelope: the score is scan.result.compliance_score, not a top-level score. Prefer the saved JSON for inspection because the console summary expects some older response fields. JSON output files avoid mixing progress messages with report data on stdout.

PDF output formats are console, json and csv. Use JSON for the complete nested response. A directory scan writes a results array and records per-file errors; it can finish successfully even when individual files fail. Inspect every entry before treating a batch as complete. The advertised --skip-ocr flag is not accepted by the released PDF API route, so do not rely on it to change server OCR behavior.

Scan versus remediate

A scan reports findings. Requesting a remediated document is a separate operation using a completed scan ID:

# Replace SCAN_ID with a completed scan you can access
aelira remediate SCAN_ID --format json

# Request remediation and attempt to download the resulting file
aelira remediate SCAN_ID --download --output reviewed-document.pdf

Choose the output extension for the document format. The server determines eligibility and available fixes. Review the remediation response and resulting document before publishing it. The CLI catches download failures without necessarily failing the command; verify that the expected file exists and inspect it. A successful command alone does not establish that an artifact was downloaded or that every finding was fixed.

See the review and remediation guide for eligibility, durable outcomes and review requirements.

Local web checks and server web scans

aelira scan http://localhost:3000 --format json --output web-result.json
aelira scan ./index.html --format html --output accessibility-report.html

aelira scan runs axe-core in local Playwright Chromium. Changing its --mode flag does not activate additional local engines. The default scan does not need an API key; optional server PDF report generation does use the API.

The separate aelira scan web command calls the server. In v0.9.11 its single-URL helper does not poll the asynchronous response for a completed result. For a complete server workflow, follow the authenticated API submit → poll → retrieve example.

CI checks and exit codes

aelira ci runs axe-core locally in Playwright Chromium; it does not submit a backend job or require an Aelira API key. Give it a reachable URL, an HTML file, or a directory containing index.html. A directory check loads that one index file, not every page in the directory. Serve an application locally first when it needs HTTP resources or routing.

# Keep the command's exit code as the pipeline result
CI=true aelira ci http://localhost:3000 \
  --threshold 85 --fail-on serious \
  --format sarif --output results.sarif

# Alternative report format
CI=true aelira ci ./dist/index.html \
  --threshold 85 --fail-on serious \
  --format junit --output results.xml

Defaults: --threshold 80, --fail-on serious, --timeout 30000 (page-load milliseconds). Formats: console, JSON, JUnit XML and SARIF. Use --output to save the report, and --badge to write an optional SVG score badge.

Treat every nonzero exit as a failure, including argument parsing or unexpected process errors. Severity order is critical, serious, moderate, minor. The JSON passedThreshold field only reflects the score threshold; the process exit code also applies --fail-on. The JUnit report's finding classification is fixed to critical/serious and does not replace the configured process exit policy.

The CI score starts at 100 and deducts 20 per critical rule violation, 10 per serious, 5 per moderate and 2 per minor, bounded to 0–100. It differs from the local scan command's score. These automated checks require additional human accessibility testing.

Other command families

aelira history --help
aelira issues --help
aelira canvas --help
aelira integrations --help
aelira report --help
aelira bulk --help

Use help to inspect the required arguments and options for history, issue tracking, Canvas, integrations, reports and bulk operations. Server features still require the relevant account permissions and integration setup.