Setup

Setup readiness.

Use this before any operational workflow. It confirms that the CLI runs, the API key is connected, and Xyte can answer basic API checks.

New to Xyte? Terms like tenant, profile, and provider are explained on the glossary page.

Ask an agent

Give the agent the outcome you need. It will check the local runtime, connect through the saved API key, and tell you whether this machine is ready for real tenant work.

Can you check whether this machine is ready to use xyte-cli?

What the agent will do

DiscoverCheck readinessConfirm the CLI, setup profile, and tenant connectivity.
InspectRead statusRun status and doctor checks before any operational work.
ChooseSetup pathUse existing setup or ask for missing tenant/key-file details.
WriteSave diagnosticsCapture useful status output when something blocks setup.
ReturnHandoffSay what works, what is blocked, and what to run next.

Ask how it works first

If setup terms are unfamiliar, ask first. The agent can explain what the status checks mean before it touches local configuration.

What does xyte-cli setup status check?
How do I connect xyte-cli to a tenant?
Why is config doctor failing?

If the agent cannot run shell commands, use the Terminal Commands view instead.

Goal

A complete setup result means three things: the command resolves on PATH, the key is stored outside the repository, and the tenant responds before you run fleet, incident, Edge, or report commands.

Commands

Check the local command environment

Start here even if you think the CLI is installed. The doctor tells you whether to use the installed binary, npx, or a workspace-local install.

# not installed yet? run any command through npx:
# npx -y @xyteai/cli@latest doctor environment --format text
xyte-cli doctor environment --format text
xyte-cli doctor install --format text
xyte-cli --version

Connect the API key without exposing the secret

Create the API key in Xyte and save it in a plain text file outside the project folder. The CLI stores it under the active profile, using default unless you choose another label.
```
xyte-cli setup run \
  --non-interactive \
  --key-file <path-outside-workspace> \
  --format json
```
Confirm readiness and connectivity

Run both checks. xyte-cli setup status reads the selected profile; xyte-cli config doctor checks whether the key can actually reach the service.
```
xyte-cli setup status --format text
xyte-cli config doctor --format text
xyte-cli status --mode fast --format json
```

Read the output

xyte-cli setup status shows the active profile and setup readiness.
xyte-cli config doctor reports connected. If it does not, fix this before using operational commands.
xyte-cli status --mode fast gives a compact machine-readable readiness result for scripts and agents.

Profile: default
State: ready
Connectivity: connected
Missing setup: none

Continue when the CLI can reach the tenant and connectivity is connected. If setup is missing, the key cannot reach the tenant, or provider scope is wrong, stop here and fix setup before moving on.

Make this repeatable

# Environment
XYTE_KEY_FILE=~/Desktop/xyte-api-key.txt

# Rerun path
xyte-cli setup run --non-interactive --key-file "$XYTE_KEY_FILE" --format json
xyte-cli config doctor --format json

If it fails

xyte-cli is not found

Run npx -y @xyteai/cli@latest doctor environment --format json and use the command recommended in the report.

Xyte cannot be reached

Run setup again with the key file. If provider auto-detection fails, ask your admin whether the key is organization or partner scoped.

Connectivity fails

Check network access, key scope, and provider selection. If you are intentionally offline, run setup with an explicit provider and --connectivity never.