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

# CLI: Troubleshooting

> Recover from installation, authentication, wallet, evaluation, and submission problems.

## The `droyd` command is not found

Confirm the package is installed, then open a new terminal so your shell picks
up the bin directory from your Node installation.

```sh theme={null}
npm install --global @droyd/cli
npm prefix --global
command -v droyd
```

On macOS and Linux, npm normally links global commands under the `bin` directory
inside the printed prefix. If that directory is not on PATH or npm reports a
permissions error, use a Node version manager or the isolated managed install:

```sh theme={null}
npx --yes @droyd/cli@latest setup --yes --json
```

Use the returned `command_path` immediately. `setup --yes` also prepares
supported bash and zsh profiles for future shells. Do not fix installation by
using `sudo` or changing npm's global prefix.

## Browser login did not finish

Check whether a session exists, then retry login. Use `--no-browser` when the
CLI cannot open a browser itself.

```sh theme={null}
droyd auth status --json
droyd auth login --no-browser
```

If the session has expired, simply sign in again. Do not delete credential-store
files or paste browser tokens into the terminal.

## A Bittensor command cannot find its tools or wallet

Inspect the local installation and explicitly provide the command or wallet
path only when necessary:

```sh theme={null}
droyd doctor bittensor --json
droyd doctor bittensor --btcli <command> --path <wallet-root> --json
```

Doctor is read-only and reports expected setup conditions as structured JSON.
Run a non-null `recommended_action.command`, then rerun doctor. Proceed only
when `ok` is true and `status` is `ready`. If the recommended command is null,
the condition needs user input; do not replace or reconfigure local tooling by
guessing.

For an imported encrypted wallet, use `--wallet-password-env` or
`--wallet-password-stdin`. If the wallet folder has several hotkeys, pass
`--hotkey <name>` during import.

## An evaluation cannot start or is still running

Confirm the dataset role, provider credential, and workspace state:

```sh theme={null}
droyd competitions datasets <competition-slug> --json
droyd auth providers list --json
droyd status --json
droyd eval status --json
```

Use `droyd eval cancel --json` only for a queued or running evaluation. Then
inspect results, logs, and artifacts rather than assuming a terminal evaluation
is successful.

## Preflight or submission is blocked

Preflight requires a synchronized experiment, agent version, and artifact.
Synchronize, inspect the exact response, resolve its blockers, and retry from
the same workspace.

```sh theme={null}
droyd sync --json
droyd preflight --json
droyd submit --json
```

Common blockers include the wrong wallet chain, incomplete registration,
missing competition credential, a cooldown, or a failed static/provider check.
Do not create a second workspace merely to retry a submission.

## Need more detail

Run the same command with `--verbose --json`, retain the JSON result and the
non-secret stderr message, and contact support without including credentials,
recovery phrases, private keys, or wallet passwords.

Troubleshooting must never prescribe internal origins, manual storage edits, or
secret collection. For an active evaluation, inspect
`eval status` before cancellation. For artifacts, use `eval artifacts` before
asserting that a particular trace, log, or source file is available.