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

# Troubleshooting

> Solutions to common issues when using the Nexudus CLI and Agent Skills.

# Troubleshooting

## CLI issues

### `nexudus` command not found

The CLI is installed as a .NET global tool. Make sure:

1. You have the [.NET SDK](https://dotnet.microsoft.com/download) installed (version 8 or later).
2. You ran `dotnet tool install --global Nexudus.Cli`.
3. The .NET tools directory is in your system `PATH`:
   * **Windows:** `%USERPROFILE%\.dotnet\tools`
   * **macOS/Linux:** `~/.dotnet/tools`

### API connection failures

If `nexudus doctor` reports that the API is unreachable:

* Check your internet connection.
* Verify the base URL is correct: `nexudus config get base-url` (default: `https://spaces.nexudus.com`).
* Check whether a proxy or firewall is blocking outbound HTTPS connections.

### Credential storage errors on Linux

The CLI uses `libsecret` for credential storage on Linux. If you get errors:

```bash theme={null}
# Install libsecret (Ubuntu/Debian)
sudo apt-get install libsecret-1-0 libsecret-1-dev

# Install libsecret (Fedora/RHEL)
sudo dnf install libsecret libsecret-devel
```

Make sure a keyring service (GNOME Keyring or KDE Wallet) is running.

### Commands return empty results

* Confirm you are authenticated: `nexudus whoami`.
* Check that your account has permissions for the entity type you're querying.
* Try broadening your search: remove `--query` filters or increase `--size`.

## Agent Skill issues

### AI assistant doesn't recognise the Nexudus skill

1. Verify the skill is installed: `npx skills list` should show `nexudus`.
2. Restart your editor or AI assistant session — skills are loaded at startup.
3. If using VS Code with GitHub Copilot, try reloading the window (`Ctrl+Shift+P` → "Reload Window").

### AI assistant returns "Not logged in" errors

The AI assistant calls the CLI, which needs active credentials:

```bash theme={null}
nexudus login
```

After logging in, retry your request.

### AI assistant constructs incorrect commands

The skill file may be outdated. Update to the latest version:

```bash theme={null}
npx skills add Nexudus-Ltd/nexudus-coworking-skills
```

You can also ask your assistant to run `nexudus <entity> <command> --help` to discover the correct options.

### Pagination issues

By default, list commands return 25 results per page. If you're not seeing all your data:

* Ask for a larger page: *"List all products with page size 100"*
* Or paginate: *"Show page 2 of products"*

## Telemetry issues

### Commands are slow or timing out

Telemetry is sent to a remote service and has a 3-second timeout. If telemetry is slow:

1. Verify the timeout isn't blocking your commands — the CLI continues even if telemetry fails.
2. Disable telemetry if you prefer: `nexudus config set telemetry off`
3. Check your network connection — poor connectivity may cause timeouts.

### Can't disable telemetry

To disable telemetry:

```bash theme={null}
nexudus config set telemetry off
```

To verify it's disabled:

```bash theme={null}
nexudus config get telemetry
```

If telemetry key doesn't exist, telemetry is enabled by default. Explicitly set it to `off` to disable.

### Want to verify telemetry is disabled

You can verify by:

1. Checking your config: `nexudus config get telemetry` should return `off`
2. Checking the config file at `~/.nexudus/config.json` — it should contain `"telemetry": "off"`
3. Enabling debug mode to check local logs: `nexudus config set telemetry-debug on` and checking `~/.nexudus/telemetry.jsonl`

For detailed telemetry information and privacy details, see the [Telemetry](/cli/telemetry) documentation.

## Getting help

* **CLI help:** `nexudus --help` or `nexudus <command> --help`
* **Diagnostics:** `nexudus doctor`
* **GitHub Issues:** [nexudus-coworking-skills](https://github.com/Nexudus-Ltd/nexudus-coworking-skills/issues)
* **Nexudus Help Center:** [help.nexudus.com](https://help.nexudus.com)