# FAQ & Troubleshooting

## Authentication

### "Access is not authorized without a valid session"

Your API token is invalid or expired.

- Verify with: `purplemet-cli auth check`
- Create a new token: [cloud.purplemet.com/#/tokens/create](https://cloud.purplemet.com/#/tokens/create)
- Check the env var is set: `echo $PURPLEMET_API_TOKEN`

### "api http 401"

Same as above. The token is not recognized by the API.

### "api http 403: ..."

The API rejected the request for the current token. The CLI surfaces the raw API response after the `api http 403:` prefix. The most common case is an admin-only command (`users`, `sessions`, `tokens`) run with an OPERATOR or READER token, which returns:

```
api http 403: {"code":"API_METHOD_NOT_ALLOWED","error":"Access to this method is not allowed to entity"}
```

Use an ADMIN token for those commands, or check the token's permissions in the Purplemet dashboard.

### "API token is required: set PURPLEMET_API_TOKEN or use --token"

No token was configured. Set it via one of:

```bash
# Environment variable (recommended)
export PURPLEMET_API_TOKEN=your-token

# CLI flag
purplemet-cli analyze https://app.com --token your-token

# .env file in current directory
echo "PURPLEMET_API_TOKEN=your-token" > .env
```

## Network

### "network: connection refused" / "network: no such host"

- Check your internet connection
- Verify `PURPLEMET_BASE_URL` is correct
- If behind a proxy, set `HTTP_PROXY` / `HTTPS_PROXY`

### "api http 429: Too Many Requests"

Rate limit reached. The CLI automatically retries with `Retry-After`. If persistent:
- Reduce analysis frequency
- Contact Purplemet support for limit increase

### "timeout: polling timeout exceeded (--wait-timeout)"

- Increase `--wait-timeout` (default: unlimited)
- Increase `--timeout` for slow networks (default: 30s)
- Check that the target URL is publicly reachable

### "x509: certificate signed by unknown authority"

The CLI could not verify the TLS certificate of the **Purplemet API endpoint** it connects to (`--base-url` / `PURPLEMET_BASE_URL`) — e.g. a self-signed certificate, an internal API gateway, or a missing CA in the local trust store. This concerns the CLI-to-API connection only: the scanned target URL is fetched server-side by the Purplemet platform, so `--insecure` has **no effect** on any target-site certificate.

- For development against such an endpoint: add `--insecure` (skips TLS verification of the API connection only — vulnerable to MITM, dev only)
- For production: ensure the proper CA certificates are installed in the system trust store

## Analysis

### "analysis ended with status ERROR"

The analysis failed on the Purplemet platform. Check the detailed error in the Purplemet dashboard for the specific cause (typically the target URL was unreachable, returned an unexpected response, or was blocked).

### `[purplemet] FAILED  severity: severity gate: ... (threshold: ...)`

Expected behavior when `--fail-on-severity` (or any other `--fail-on-*` flag) is set
and the analysis violates the gate. The CLI prints one `FAILED` line per failing
gate to stderr, then a `N/M gate(s) failed` summary, and exits with code `1`.

Common gate messages emitted by the CLI:

- `severity gate: 1 critical, 2 high (threshold: high)`
- `rating gate: D (threshold: C)`
- `CVSS gate: 9.8 >= 9.0 (CVE-2024-...)`
- `EOL gate: 2 end-of-life component(s) (jQuery 2.1.4, PHP 7.4)`
- `KEV gate: 3 CISA Known Exploited Vulnerability(ies) detected`
- `EPSS gate: 0.85 >= 0.75 (CVE-2024-...)`
- `WAF gate: no WAF detected`
- `cert expiry gate: 1 certificate(s) expiring within 30 days (...)`

Options to react:
- Fix the vulnerabilities
- Adjust the threshold (e.g. `--fail-on-severity critical` is less strict)
- Remove the flag to disable the gate
- Acknowledge the risk with `purplemet-cli issues ignore` (ignored issues are always excluded from gate evaluation)

### "no site found for URL and creation disabled"

You used `--no-create` but the URL doesn't match any existing site. Either:
- Remove `--no-create` to auto-create
- Use the site UUID instead of URL: `purplemet-cli sites list` to find it

### "argument is neither a UUID nor a valid URL"

The argument to `analyze` must be either:
- A valid URL starting with `http://` or `https://`
- A valid UUID (e.g. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)

### Analysis exceeds the default timeout

If polling reaches `--wait-timeout` before the analysis completes, the CLI exits with code 3. Raise the timeout for large sites:

```bash
purplemet-cli analyze <url> --wait-timeout 600000   # 10 minutes
```

Refer to the [Purplemet documentation](https://cloud.purplemet.com/docs/#/web%20applications/launch-analyses) for details on how analyses run.

## Output

### How do I get JSON output?

```bash
purplemet-cli analyze https://app.com --json
# or
purplemet-cli analyze https://app.com --format json
```

### How do I save the report to a file?

```bash
# Any format
purplemet-cli analyze https://app.com --format json --output-file report.json
purplemet-cli analyze https://app.com --format html --output-file report.html
purplemet-cli analyze https://app.com --format sarif --output-file results.sarif
```

### How do I generate a SARIF report?

```bash
purplemet-cli analyze https://app.com --format sarif --output-file results.sarif
```

SARIF 2.1.0 output is compatible with GitHub Code Scanning, Azure DevOps Advanced Security, and any SARIF-compatible viewer.

### How do I interpret the security rating?

Ratings (`A`–`F`) are computed and defined by the Purplemet platform. See the [official Purplemet documentation](https://cloud.purplemet.com/docs/#/web%20applications/security-rating) for authoritative definitions.

## CI/CD

### "PURPLEMET_API_TOKEN is not set"

Set the token as a secret/variable in your CI platform:
- **GitHub**: Settings → Secrets and variables → Actions → New repository secret
- **GitLab**: Settings → CI/CD → Variables (mark as masked)
- **Bitbucket**: Repository Settings → Pipelines → Variables (mark as secured)
- **Jenkins**: Manage Jenkins → Credentials → Add credentials
- **Azure DevOps**: Pipelines → Library → Variable Groups (mark as secret)

### Analysis takes too long in CI

- Set `--wait-timeout 300000` (5 min) to bound execution
- Check that the target URL is reachable from the internet

### Exit code 1 but I want the pipeline to continue

Use the appropriate mechanism for your CI platform:

| Platform | Mechanism |
|----------|-----------|
| GitHub Actions | `continue-on-error: true` |
| GitLab CI/CD | `allow_failure: true` or `allow_failure: exit_codes: [1]` |
| Bitbucket | `after-script` for post-processing |
| Jenkins | Mark build `UNSTABLE` instead of `FAILURE` |
| Azure DevOps | `continueOnError: true` |

Example (any platform):

```bash
purplemet-cli analyze https://app.com --json --fail-on-severity high || true
```

### How do I run analyses on multiple sites?

Use a matrix/parallel strategy in your CI platform, or loop in shell:

```bash
for URL in https://app1.com https://app2.com https://app3.com; do
  purplemet-cli analyze "$URL" --json --fail-on-severity high || true
done
```

### How do I compare analyses over time?

Use the `diff` command to compare two analyses:

```bash
purplemet-cli diff <analysisId1> <analysisId2> --site-id <siteId>
```

## Docker

### "exec format error"

Wrong architecture. Use the correct image for your platform:
- `ppmsupport/purplemet-cli:latest` supports `linux/amd64` and `linux/arm64`
- Specify platform: `docker run --platform linux/amd64 ...`

### "certificate verify failed"

Add `--insecure` flag (dev only) or ensure CA certificates are available in the container.

### How do I use a specific CLI version with Docker?

```bash
docker run --rm -e PURPLEMET_API_TOKEN=<token> ppmsupport/purplemet-cli:v1.2.0 analyze https://app.com
```

## General

### Where do I create an API token?

Go to [cloud.purplemet.com/#/tokens/create](https://cloud.purplemet.com/#/tokens/create).

### Where can I see my analysis results online?

Log in to [cloud.purplemet.com](https://cloud.purplemet.com) to view your sites, analyses, and detailed findings in the Purplemet dashboard.

### How do I schedule recurring analyses?

```bash
# Daily at 2am
purplemet-cli sites schedule <siteId> --frequency DAILY --time 02:00

# Weekly on Monday at 2am
purplemet-cli sites schedule <siteId> --frequency WEEKLY --day monday --time 02:00
```

Or use your CI/CD platform's scheduling (e.g. GitHub Actions `schedule`, GitLab `schedules`).

### How do I get support?

- Documentation: [docs/](.)
- Issues: Contact Purplemet support