npm package: @qanode/cli
Description: Official QANode CLI for CI/CD and automation workflows
Latest version: 0.1.1

# `@qanode/cli`

Official QANode CLI for CI/CD and automation workflows.

It lets you:
- authenticate with an integration token
- run scenarios and suites
- wait for execution completion
- inspect an existing run
- download the consolidated run report

## Installation

You can use it without a global install:

```bash
npx @qanode/cli help
```

If you prefer to install it in your project:

```bash
npm install --save-dev @qanode/cli
```

Then run:

```bash
npx qanode help
```

## Configuration

Set:

- `QANODE_URL`: the public QANode URL, usually the same domain your team opens in the browser
- `QANODE_TOKEN`: an integration token or session token

Example:

```bash
export QANODE_URL=https://company.qanode.com
export QANODE_TOKEN=qnt_xxxxx
```

In local development with Vite, `http://localhost:3000` may also work as long as it proxies `/api`.

## Commands

```bash
qanode auth me [--json]

qanode run scenario (--scenario-id <id> | --scenario-name <name>) \
  [--project-id <id> | --project-name <name>] \
  [--var NAME=VALUE] \
  [--credential CRED.FIELD=VALUE] \
  [--wait] \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

qanode run suite (--suite-id <id> | --suite-name <name>) \
  [--project-id <id> | --project-name <name>] \
  [--var NAME=VALUE] \
  [--credential CRED.FIELD=VALUE] \
  [--wait] \
  [--interval <seconds>] \
  [--timeout <seconds>] \
  [--json]

qanode runs get --run-id <id> [--json]
qanode runs wait --run-id <id> [--interval <seconds>] [--timeout <seconds>] [--json]
qanode runs artifacts --run-id <id> --out <dir> [--json]
```

## Output

Without `--json`:
- `run ... --wait`
- `runs get`
- `runs wait`

return only:

```bash
success
```

or

```bash
failed
```

or

```bash
cancelled
```

This makes the CLI easier to use in pipelines.

With `--json`, the CLI prints the full API payload.

Important:
- `qanode run ... --json` without `--wait` returns the start payload, which contains `runId`
- `qanode run ... --wait --json` returns the final run object, which contains `id`
- `qanode runs artifacts` should use the same run ID from the execution you already started
- do not call `qanode run ...` again just to discover the run ID, or you will create a second execution

## Examples

Run a suite by ID:

```bash
npx @qanode/cli run suite --suite-id SUITE_ID --wait
```

Run a suite by project and name:

```bash
npx @qanode/cli run suite \
  --project-name "Backoffice" \
  --suite-name "Login Regression" \
  --wait
```

Run a scenario by project and name:

```bash
npx @qanode/cli run scenario \
  --project-name "Checkout" \
  --scenario-name "Login API" \
  --wait
```

Run a scenario with execution overrides:

```bash
npx @qanode/cli run scenario \
  --scenario-id SCENARIO_ID \
  --var BASE_URL=https://preview.app \
  --credential api-main.token=$API_TOKEN \
  --wait
```

Download the consolidated run report:

```bash
npx @qanode/cli runs artifacts \
  --run-id RUN_ID \
  --out ./artifacts
```

The command above prioritizes the consolidated PDF report and saves it as:

```bash
report_<runId>.pdf
```

## GitHub Actions

```yaml
- name: Run QANode suite
  id: run_suite
  run: |
    set +e
    RUN_JSON=$(npx @qanode/cli run suite \
      --project-name "Backoffice" \
      --suite-name "Login Regression" \
      --wait \
      --json)
    EXIT_CODE=$?
    set -e

    echo "$RUN_JSON" > qanode-run.json
    echo "run_id=$(echo "$RUN_JSON" | jq -r '.id')" >> "$GITHUB_OUTPUT"
    exit $EXIT_CODE
  env:
    QANODE_URL: ${{ secrets.QANODE_URL }}
    QANODE_TOKEN: ${{ secrets.QANODE_TOKEN }}

- name: Download QANode report
  if: always()
  run: |
    npx @qanode/cli runs artifacts \
      --run-id "${{ steps.run_suite.outputs.run_id }}" \
      --out ./artifacts
  env:
    QANODE_URL: ${{ secrets.QANODE_URL }}
    QANODE_TOKEN: ${{ secrets.QANODE_TOKEN }}
```

## Azure DevOps

```yaml
steps:
- script: |
    set +e
    RUN_JSON=$(npx @qanode/cli run suite \
      --project-name "Backoffice" \
      --suite-name "Login Regression" \
      --wait \
      --json)
    EXIT_CODE=$?
    set -e

    echo "$RUN_JSON" > qanode-run.json
    echo "##vso[task.setvariable variable=QANODE_RUN_ID]$(echo "$RUN_JSON" | jq -r '.id')"
    exit $EXIT_CODE
  displayName: Run QANode suite
  env:
    QANODE_URL: $(QANODE_URL)
    QANODE_TOKEN: $(QANODE_TOKEN)

- script: |
    npx @qanode/cli runs artifacts \
      --run-id "$(QANODE_RUN_ID)" \
      --out ./artifacts
  displayName: Download QANode report
  condition: always()
  env:
    QANODE_URL: $(QANODE_URL)
    QANODE_TOKEN: $(QANODE_TOKEN)
```

## Per-execution overrides

Overrides passed through the CLI:
- affect only that execution
- do not permanently overwrite the value stored in QANode

Examples:

```bash
--var BASE_URL=https://preview.app
--var LOCALE=en-US
--credential api-main.token=$API_TOKEN
--credential smtp-main.password=$SMTP_PASSWORD
```

## Notes

- When using names, prefer combining `--project-name` with `--suite-name` or `--scenario-name` to avoid ambiguities.
- The CLI uses QANode `/api` routes directly, so it works well behind a public domain and reverse proxy.
- In CI pipelines, the most common pattern is using `--wait` and relying on the process exit code.