Troubleshooting

When something is not working.

Start with one diagnostic command, then jump to the section that matches what you see. New to the terms here? Open the glossary.

Check this first

Most problems show up in one of these three read-only checks. Run them before anything else.

# Is this machine able to run the CLI at all?
xyte-cli doctor environment --format json

# Is a tenant connected, and can Xyte answer?
xyte-cli config doctor --tenant <tenant-id> --format text

# Fast readiness summary for operators and agents
xyte-cli status --mode fast --format json

If xyte-cli is not found, run any command with npx -y @xyteai/cli@latest in front, then fix your install. If a tenant is not connected, run Set up and verify readiness.

Setup & connection

Node.js is missing or too old

Install Node.js 22 or newer, or run the command in an environment that already has it. doctor environment reports the version it found.

The key file cannot be read

Move the key file outside the repository, check its permissions, and rerun setup. Never paste a key on the command line.

Authentication is rejected

Ask your Xyte admin for a fresh key with access to the tenant, then rerun xyte-cli setup run. Keys are created in Xyte under Settings → API Keys.

Network access fails

Fix VPN, firewall, or proxy access, then run xyte-cli config doctor --tenant <tenant-id> again.

Results look incomplete

The wrong provider scope may be in use. On a read command add --provider-scope organization or --provider-scope partner (on flow run use --inspect-provider-scope). See provider scope.

Native storage is unavailable

A warning that the CLI fell back to file storage is not a failure. To inspect where credentials live, run xyte-cli config path --format json.

Output & reading

I get colored text, not JSON

In an interactive terminal, output defaults to human-readable text. Add --output json (and --strict-json when a job parses it) to force machine-readable output.

Counts differ from the web view

Compare filters first: status, date range, page size, and whether the UI hides older active incidents.

Repeated error frames in a watch

Run xyte-cli config doctor --tenant <tenant-id> --format text, then retry the watch with --once. Keep the previous good snapshot until a clean frame returns.

A watch runs too long

Bound it with --max-polls. Do not leave an unbounded watch running in a support handoff.

A report command rejects the input

Confirm the input came from xyte-cli ops inspect deep-dive, not ops inspect fleet, and that you passed both --input and --out.

Writes & flow gates

A flow paused at a gate

That is expected for write-capable flows. Read nextAction, then resume the same run with --apply --resume <run-id-or-path> after approval. Do not retype an apply command from memory.

Resume fails

Use the original run id or bundle path from the plan output. If tenant state changed, run --plan again first.

A batch was interrupted

Rerun with the matching --resume-artifact <path> instead of starting over, so completed rows are not claimed twice.

No command is available to remediate

Stop. Read the device with organization.devices.getDevice, describe its model with xyte-cli edge models describe, and choose only from commands[].name or commands[].friendly_name. Use custom_fields for command parameters and pass command_file_id when with_file is true. Do not guess a command from another device model.

Remove or reset

These commands change local state. Removing a key or tenant requires --confirm; the CLI clears the stored secret.

# See what is stored locally
xyte-cli config tenant list
xyte-cli config key list --tenant <tenant-id>

# Remove one stored key slot (clears its secret)
xyte-cli config key remove \
  --tenant <tenant-id> \
  --provider <xyte-org|xyte-partner> \
  --slot <slot-id-or-name> \
  --confirm

# Remove a whole tenant profile and clear its known key slots
xyte-cli config tenant remove <tenant-id> --confirm

# Uninstall the CLI (global install)
npm uninstall -g @xyteai/cli

After offboarding a machine, remove the tenant profile and delete any leftover key file you created during setup.

Report a bug

When you need to share what happened, capture the action logs instead of pasting secrets. Logs record commands, not key values.

xyte-cli logs list --output text
xyte-cli logs show --request-id <request-id> --output json

Still stuck?

Open an issue with the failing command, the redacted output, and the relevant log entry on GitHub.

Not sure what a term means

Check the glossary for tenant, profile, space, incident, flow, and more.