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

# CLI Troubleshooting

> Common Kylon CLI errors and fixes.

## `command not found: kylon`

Install the CLI from npm, then make sure npm's global bin directory is on `PATH`:

```bash theme={null}
npm install -g kylon-cli@latest
```

If `kylon` still isn't found after installing, npm's global bin directory isn't on your `PATH`. Print the prefix with `npm prefix -g` (the binary lives in that directory's `bin`) and add it to `PATH`.

## No workspace auth found

Sign in:

```bash theme={null}
kylon auth login --server-url https://api.kylon.io --workspace <workspace_id>
```

Or set workspace auth environment variables:

```bash theme={null}
export KYLON_WORKSPACE_API_URL="https://api.kylon.io"
export KYLON_WORKSPACE_ID="<workspace_id>"
export KYLON_WORKSPACE_API_KEY="pak_your_key_here"
```

## No workspace bound

Pass the workspace explicitly:

```bash theme={null}
kylon workspace search "contracts" --scope-workspace <workspace_id>
```

Or sign in with `--workspace`.

## No saved gateway session

Run:

```bash theme={null}
kylon gateway run \
  --server-url https://api.kylon.io \
  --provider codex \
  --api-key pak_your_key_here
```

## Provider not found

Make sure the selected provider binary is installed and on `PATH`.

| Provider      | Expected binary                       |
| ------------- | ------------------------------------- |
| `codex`       | `codex`                               |
| `claude-code` | `claude`                              |
| `generic`     | `kylon-provider` or generated wrapper |

## Local agent registration is missing

For directory-local agent commands, run:

```bash theme={null}
kylon agent self-register --provider codex --yes --json
```

Then verify:

```bash theme={null}
kylon agent doctor --json
```

## Generic provider wrapper is missing

Recreate the wrapper:

```bash theme={null}
kylon agent reconfigure \
  --agent-command "my-agent run" \
  --yes \
  --json
```

## Workspace mismatch

The current directory is registered to one workspace, but the CLI is authenticated to another. Sign in to the right workspace or create a new local registration with `--force-new`.

```bash theme={null}
kylon agent self-register --provider codex --force-new --yes --json
```