CLI troubleshooting

Start with a small set of local and authenticated checks:

champrep version
champrep config path
champrep config env
champrep auth whoami
champrep auth status

Do not paste API keys, browser tokens, webhook secrets, or unredacted debug output into a support request.

Command not found

Confirm that the binary exists and is on PATH:

command -v champrep
echo "$PATH"

The direct installer normally uses $HOME/.local/bin for a non-root user. Add that directory to the shell startup file and open a new terminal. If multiple copies are installed, remove the older one or put the intended directory first in PATH.

Browser login does not open

Use headless approval:

champrep auth login --no-browser

Open the displayed URL in a trusted browser. If approval expires, start a new login rather than reusing the old URL.

Authentication required or invalid

champrep auth list
champrep auth whoami

Check whether CHAMPREP_TOKEN is set. It overrides the keychain for the current process and can make the CLI use a different credential than expected.

test -n "$CHAMPREP_TOKEN" && echo "ephemeral token override is active"

Do not print the value. Renew browser login or replace a revoked automation key as appropriate.

Wrong account, profile, or environment

champrep auth list
champrep auth switch PROFILE
champrep config env
champrep --env production auth whoami

A profile switch stays within an account already authenticated on the machine. Authenticate separately to add a different account.

Insufficient scope or access denied

The credential can be valid while the request is denied by its scope, active plan, service availability, organization policy, role, or resource permission.

1. Run champrep auth status.
2. Identify the command’s required service scope.
3. Review the key in the API Keys dashboard.
4. Confirm the active profile can perform the same action in the service UI.
5. Create or rotate to a least-privilege key with the missing scope when the workload is authorized to have it.

Rate limited

Exit code 5 means a current Gateway limit was reached. Wait for the indicated retry period, reduce parallel work, and avoid frequent polling. Limits are driven by current account configuration; do not make a script assume a fixed number for a plan name.

Network or service failure

Use metadata-only verbose output first:

champrep --verbose auth whoami

--debug can include request or response bodies. Use it only in a controlled terminal and review the output before sharing it.

Check DNS, proxy, firewall, and TLS inspection settings. The CLI must reach the CHAMPREP API Gateway over HTTPS. CHAMPREP_API_URL, when used for development, must identify a Gateway-compatible endpoint and not an individual service API.

For 502, 503, or 504, retry a safe read with bounded backoff. Do not repeat a create, update, send, or delete until you know whether the first request took effect.

Collect a safe support report

Include:

• champrep version output;
• operating system and architecture;
• the command name with sensitive arguments removed;
• the selected environment name;
• the exit code;
• the HTTP status and stable error code;
• the approximate time and timezone of the failure.

Exclude credentials and sensitive content. Then contact CHAMPREP Support.