Troubleshooting

Real failure modes, verified against the CLI's source, not a generic FAQ. If something here doesn't match what you're seeing, open an issue.

redential logindoesn't open a browser

Expected on a headless machine, over SSH, or if no browser/opener binary is available. Auto-opening the verification URL is a best-effort convenience, never load-bearing. Any failure to open it (unknown platform, no browser installed, the opener binary missing) is silently swallowed, and login proceeds exactly as if auto-open didn't exist.

Look for the printed verification_uri and code in your terminal output and open the URL yourself, then enter the code:

First, go to: https://www.redential.com/cli/activate
Then enter this code: WDJB-MJHT
Waiting for confirmation...

Auto-open only ever tries http/https URLs, never a file://or custom scheme, and only via your OS's native opener (never a shell string). This failing safely-shut is expected behavior, not a bug to work around with elevated permissions or a different shell.

Scanning very large repositories

scanwalks git history once, streaming the whole way through: it never buffers a huge repo's full git log output in memory, and diff content for skill detection is fetched in bounded batches rather than one git process per commit. On a real terminal, it prints a running progress line to stderr (never stdout) while it walks:

scanning commits... 12,400/80,000

Piped or redirected stdout gets no progress output at all. scan's stdout contract, the exact bundle JSON, byte-identical either way, is unaffected regardless of repo size.

Limiting the walk with --since

For a repository with an unusually long history, --since <spec>limits the walk, not the truth: it changes which commits the bundle's fields are computed over (commit volume, span, the hour/weekday histograms, ownership), it never adds or fabricates activity. Two fields stay window-independent on purpose, repo.age_days and repo.repo_fingerprint, so a windowed scan can never make an old repo look freshly created.

redential scan --since 2years
redential scan --since 2024-01-01

Shallow clones

A shallow clone (git clone --depth N, or the default checkout depth of most CI actions) is missing history before its shallow boundary entirely, not filtered out like --since. When scan/submit detect one, they print a warning naming the remedy (git fetch --unshallow) and continue with whatever history is available, so commit volume, span, and repo age don't silently understate real activity with no explanation.

Hangs, or fails immediately, in CI

Every interactive prompt (the authorization attestation, author selection, and submit's upload confirmation) reads from stdin. In a CI job with no attached terminal, stdin is typically closed (EOF) from the start. The CLI treats EOF on any of these prompts as a hard failure (a non-zero exit) rather than hanging forever or silently assuming an answer. No confirmation is ever inferred by default.

Run every command non-interactively instead, with the flags that answer each prompt explicitly:

redential scan --repo . --author you@company.com --yes

redential login   # once, outside CI: the session token persists locally
redential submit --repo . --author you@company.com --yes --confirm-upload --label "acme backend"

login's device flow itself has no non-interactive mode. Run it once on a machine where you can open a browser, and the stored session (~/.config/redential/credentials.json) is what a later submit --confirm-upload in CI actually uses. --label is also required non-interactively: without a terminal to prompt, submitrefuses before any network call if it's missing.

REDENTIAL_SITE_URL (development only)

The CLI talks to https://www.redential.com by default. Set REDENTIAL_SITE_URL to point login and submit at a different server: a local dev instance, or a mock server in tests.

REDENTIAL_SITE_URL=http://localhost:3000 redential login

Unset it (or don't set it) for normal use. This is a development/testing override, not a setting end users need.