> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI troubleshooting

> Recover local and WorkOS-authenticated Cloud CLI operations

<div className="flex flex-wrap gap-2"><Badge color="orange" size="sm">Troubleshooting</Badge></div>

## Authentication required

Run `helix auth login`. If an access token is near expiry, the CLI refreshes it through WFE while
holding the credential-file lock. Only a typed WFE rejection before handler dispatch can trigger one
refresh-and-retry. A normal authorization denial or any post-dispatch failure is not retried.

Old credential/config fields are intentionally rejected. Remove legacy user/admin keys, arbitrary
authorization headers, gateway URLs, and query-key fields. Service credentials and application keys
cannot be used to log the CLI in.

## Ambiguous Cloud target

Pass `--workspace`, `--project`, `cluster:<id>`, or `tenant:<id>`. Alternatively use
`helix project link` and `helix add cloud` to persist stable project/database linkage in `helix.toml`.

## Query permission denied

Project `read`/`write` does not grant database-data access. Ask an owner/admin to grant independent
`query_read` and, if required, `query_write` for the selected project. Members default to neither.

## Local connection refused

Run `helix start <instance>`, verify with `helix status <instance>`, or pass local-only `--host` and
`--port` overrides.

## Cloud logs

Cloud `--follow` is not supported. Use an RFC 3339 `--start`/`--end` range or omit both for the last
hour of query errors.