xyte-cli

Built for shell-capable AI agents and automated terminal workflows. Manual terminal use is supported for setup, debugging, and local testing.

• npm: @xyteai/cli
• GitHub Page: docs/index.html
• Command reference: docs/commands.md
• Flows: docs/flows/agent-ops.md
• Schemas: docs/schemas

Install Flow

AI agent

Use this path for Codex, Claude Code/Desktop, GitHub Copilot CLI, VS Code Copilot Agent, and other shell-capable agents. Chat-only assistants can explain commands, but they cannot install the CLI.

Start with environment diagnostics. The report picks the right install mode for this environment and returns copy-pasteable commands in recommendations:

xyte-cli doctor environment --format json

If xyte-cli is missing:

npx -y @xyteai/cli@latest doctor environment --format json

If the report recommends workspace-local mode:

npm install --prefix ./.xyte-cli/runtime @xyteai/cli@latest
./.xyte-cli/runtime/node_modules/.bin/xyte-cli <command>

PowerShell command path:

.\.xyte-cli\runtime\node_modules\.bin\xyte-cli.cmd <command>

Before you start: in Xyte, open Settings → API Keys and create a key. Save it in a plain text file outside your project folder (for example xyte-api-key.txt on your Desktop) — any text editor works. Your agent will ask for the file's path. Do not paste API keys into chat. Do not store API keys inside the repo.

Agent prompt (copy/paste):

Use @xyteai/cli in this workspace.
Never print secrets. Do not invent IDs or outputs.

First run `xyte-cli doctor environment --format json`.
If `xyte-cli` is missing, run `npx -y @xyteai/cli@latest doctor environment --format json`.
Follow the report's recommendations.nextCommand and recommendations.commands.

If `xyte-cli setup status` shows no connected tenant, ask me for the path to my API key file (never the key itself) and connect it with the report's setupKeyFile recipe.
Do not ask me to paste API keys into chat.
Do not store API keys inside the repo.
After setup succeeds, offer to delete the key file, then run `xyte-cli init --scope project --agents all --force --no-setup`.

If this surface cannot run shell commands, stop and say I need a shell-capable terminal or agent.

Detailed agent guidance: docs/agents.md.

CI / headless

1. In Xyte, open Settings → API Keys and create a key.
2. In your CI tool (GitHub Actions, GitLab CI, Jenkins), add a secret named XYTE_CLI_KEY and paste the key as its value.
3. Make sure the job receives the secret as an environment variable — in GitHub Actions add env: XYTE_CLI_KEY: ${{ secrets.XYTE_CLI_KEY }} to the step; GitLab CI passes variables automatically.
4. Add these commands to your pipeline (acme is just a name for this connection — use your company name):

npx -y @xyteai/cli@latest setup run --non-interactive --tenant acme --output json
npx -y @xyteai/cli@latest setup status --tenant acme --field tenantId

For reproducible pipelines, replace @latest with a pinned version (e.g. @0.10.7).

Manual terminal

Install Node.js 22+ first if node --version is missing or below 22 (macOS: brew install node@22, Windows: winget install OpenJS.NodeJS.LTS).

npm install -g @xyteai/cli@latest
xyte-cli --version
xyte-cli setup run
xyte-cli setup status --field tenantId
xyte-cli init --no-setup

If your global npm bin is not on PATH, replace xyte-cli in the commands below with one of these published-package fallbacks:

npx -y @xyteai/cli@latest <command>
npm exec -- @xyteai/cli@latest <command>

Use the setup status tenant value as <tenant-id> in the examples below. Persisted credentials default to secure OS-native storage: macOS Keychain, Windows DPAPI, Linux Secret Service. If native storage is unavailable, xyte-cli warns and falls back to file storage. For non-interactive automation and backend details, use the setup guidance in docs/getting-started.md.

---

Examples (Feature Catalog)

1) Endpoint discovery

xyte-cli api endpoints list
xyte-cli api endpoints describe organization.devices.getDevices

Key params:

• api endpoints describe <endpoint-key>

2) Read endpoint call (safe)

xyte-cli api call organization.devices.getDevices \
  --tenant <tenant-id> \
  --query-json '{"page":1,"per_page":100}' \
  --output-mode envelope
xyte-cli api call organization.notes.getDeviceNotes \
  --tenant <tenant-id> \
  --path-json '{"device_id":"<device-id>"}' \
  --query-json '{"page":1,"per_page":100}'

Key params:

• --tenant <tenant-id>
• --output-mode envelope for contract output
• --strict-json for machine parsing
• For organization.devices.getDevices, increment page until next_page is null/absent or the response reports has_next_page=false.

2b) Device or space notes

Create/delete note calls are writes; get explicit approval before running them.

xyte-cli api call organization.notes.createDeviceNote \
  --tenant <tenant-id> \
  --path-json '{"device_id":"<device-id>"}' \
  --body-json '{"content":"Mounted behind the left panel."}'

xyte-cli api call organization.notes.deleteDeviceNote \
  --tenant <tenant-id> \
  --path-json '{"device_id":"<device-id>","id":"<note-id>"}'

3) Incident watch (active incidents)

xyte-cli ops watch incidents --tenant <tenant-id> --profile incidents-active --once
xyte-cli ops watch incidents --tenant <tenant-id> --profile incidents-active --interval-ms 2000 --max-polls 10

Key params:

• terminal output is human-readable by default; add --output json --strict-json for machine parsing
• --once one snapshot poll and exit
• --interval-ms minimum 1000
• --max-polls bounded polling

4) Flow discovery and guided remediation

xyte-cli flow list --format text
xyte-cli flow run flow.device-command --tenant <tenant-id> --plan --var device_id=<device-id> --var command=reboot
xyte-cli flow run flow.guided-remediation --tenant <tenant-id> --var incident_id=<incident-id> --var device_id=<device-id> --var command=reboot --var updated_device_name=<device-name>

Key params:

• flow run defaults to plan mode
• --var key=value for runtime context
• non-completed runs include nextAction with the safest next operator command
• gate continuation is --apply --resume <run-id-or-path>

5) Tenant and key slots

xyte-cli config tenant add <tenant-id> --name "Acme"
xyte-cli config tenant use <tenant-id>
xyte-cli config key add --tenant <tenant-id> --provider xyte-org --name primary --key-file ~/.config/xyte/acme.key --set-active
xyte-cli config key list --tenant <tenant-id> --output json
xyte-cli config tenant remove <tenant-id> --confirm

Key params:

• config tenant remove requires --confirm
• prefer --key-file, --key-stdin, or --key-command over inline keys
• pass --provider xyte-org|xyte-partner when you need deterministic routing

6) Write example

Primary read/setup/reporting workflows are shell-neutral. Advanced raw API examples like this one remain shell-specific because inline JSON quoting differs across PowerShell, CMD, Bash, and zsh.

xyte-cli flow run flow.device-command --tenant <tenant-id> --plan --var device_id=<device-id> --var command=reboot

xyte-cli api call organization.devices.getDevice \
  --tenant <tenant-id> \
  --path-json '{"device_id":"<device-id>"}'

xyte-cli edge models describe \
  --tenant <tenant-id> \
  --model-id <model-id-from-device>

xyte-cli api call organization.commands.sendCommand \
  --tenant <tenant-id> \
  --path-json '{"device_id":"<device-id>"}' \
  --body-json '{"command":"reboot","extra_params":{}}'

Behavior:

• prefer flow.device-command for one-device command sends because it reads the device model, validates required fields and declared value types in custom_fields, and maps labels or label arrays through static options embedded in the model metadata; malformed or unresolved choices stop before the send
• the built-in flow sends the selected commands[].name under request field command; raw or custom sends may use friendly_name, while name remains model metadata rather than a send request field
• send command parameters as a JSON object under extra_params; raw sendCommand calls reject response-only params and non-object extra_params
• optional status polling requires --var command_poll=true --var command_poll_timeout_ms=<positive-ms>; add --var command_poll_interval_ms=<positive-ms> to override the 5-second interval
• polling follows command-history pages for the exact id returned by the send response, stops at the requested timeout, and reports queue/history status only
• if a send is interrupted before its result is recorded, resume stops instead of sending the command a second time
• the raw API call executes directly once you choose the write step

7) Fleet insights and deep-dive data

xyte-cli ops inspect fleet --tenant <tenant-id> --provider-scope auto --output json
xyte-cli ops inspect deep-dive --tenant <tenant-id> --provider-scope auto --window 24 --output json --out ./artifacts/deep-dive.json

Key params:

• --provider-scope organization|partner|auto
• --window <hours> for deep-dive
• --output json for pipelines

8) Generate report artifacts

xyte-cli ops report generate --tenant <tenant-id> --input ./artifacts/deep-dive.json --render pdf --out ./reports/fleet-report.pdf
xyte-cli ops report generate --tenant <tenant-id> --input ./artifacts/deep-dive.json --render markdown --out ./reports/fleet-report.md

Key params:

• --input deep-dive JSON
• --render markdown|pdf for artifact format
• --output text|json controls stdout, not report rendering

9) Headless console snapshots (for agents/automation)

xyte-cli ops console --headless --screen dashboard --once --tenant <tenant-id> --output json
xyte-cli ops console --headless --screen spaces --follow --interval-ms 2000 --tenant <tenant-id> --output json

Key params:

• --screen dashboard|spaces|...
• --once snapshot mode
• --follow stream mode

10) Utility preprocessing + executable workflows

xyte-cli util list-actions --output text --mode friendly
xyte-cli util list-actions --output text --execution-support edge.claim-batch

xyte-cli util prepare \
  --action space.import-tree \
  --input ./raw-hierarchy.xlsx \
  --output-dir ./prepared

xyte-cli util prepare \
  --action organization.connectors.prepareSetup \
  --input ./raw-connectors.csv \
  --output-dir ./prepared

xyte-cli util prepare \
  --action organization.teamAccess.groups \
  --input ./raw-team.csv \
  --output-dir ./prepared

xyte-cli util prepare \
  --action organization.teamAccess.users \
  --input ./raw-team.csv \
  --output-dir ./prepared

xyte-cli util prepare \
  --action organization.teamAccess.memberships \
  --input ./raw-team.csv \
  --output-dir ./prepared

xyte-cli util import-tree --tenant <tenant-id> --input ./prepared/space-import-tree.csv
xyte-cli util import-tree --tenant <tenant-id> --input ./prepared/space-import-tree.csv --apply --report ./reports/space-import.apply.ndjson

xyte-cli util match \
  --source ./source-devices.json --target ./target-spaces.json \
  --source-field name --target-field name \
  --out ./device-moves.csv

xyte-cli util move-devices --tenant <tenant-id> --input ./device-moves.csv
xyte-cli util move-devices --tenant <tenant-id> --input ./device-moves.csv --apply --report ./reports/device-moves.apply.ndjson

Key params:

• util prepare --action ... --input ... --output-dir ...
• util import-tree and util move-devices are dry-run unless --apply
• dry-runs count validated rows under totals.planned; totals.succeeded is for apply mode
• generated .notes.md files are the human review artifact for prepared data
• connector and team-access prepare actions are prepare-only normalization utilities
• --report writes an NDJSON row report

11) Claim devices

Use docs/claim-devices.md first when the claim path is not explicit. Native/direct, Edge, and C2C are different flows.

# Native / direct claim
xyte-cli api call organization.devices.claimDevice \
  --tenant <tenant-id> \
  --body-json '{"name":"<name>","space_id":<space-id>,"sn":"<sn>","mac":"<mac>","cloud_id":"<cloud-id>"}'

# Single Edge claim, plan first
xyte-cli edge models list --tenant <tenant-id> --page 1 --per-page 100
xyte-cli edge models describe --tenant <tenant-id> --model-id <device-model-id>
xyte-cli edge claim \
  --tenant <tenant-id> \
  --proxy-id <proxy-id> \
  --device-ip <device-ip> \
  --device-model-id <device-model-id> \
  --space-id <space-id> \
  --custom-parameters '{"SNMP community":"public","Port":"161"}' \
  --plan

# Bulk Edge claim, plan first
xyte-cli util prepare --action organization.edge.startClaim --input ./edge-devices.xlsx --output-dir ./prepared
xyte-cli edge claim-batch --tenant <tenant-id> --input ./prepared/organization-edge-startclaim.csv --plan
xyte-cli edge claim-batch --tenant <tenant-id> --input ./prepared/organization-edge-startclaim.csv --apply --report ./reports/edge-claim.apply.ndjson --resume-artifact ./reports/edge-claim.resume.ndjson

# Already-claimed Edge custom parameters, plan first
xyte-cli edge update-params \
  --tenant <tenant-id> \
  --device-id <device-id> \
  --set-json '{"Port":"161"}' \
  --plan
xyte-cli util prepare --action edge.params.update --tenant <tenant-id> --input ./edge-params.xlsx --output-dir ./prepared
xyte-cli edge update-params-batch --tenant <tenant-id> --input ./prepared/edge-params-update.csv --plan --report ./reports/edge-params.plan.ndjson

Key params:

• edge models list and edge models describe are read-only and are the source for Edge model ids and supported parameter labels
• edge claim, edge claim-batch, edge update-params, edge update-params-batch, and edge ping are mutating; run --plan first
• edge claim and edge claim-batch accept optional mac and sn fields when the source data provides them
• edge update-params and edge update-params-batch send complete replacement custom_parameters bodies after validation
• blank or skip_connectivity_check=false batch rows run a pre-claim ping before startClaim
• skip_connectivity_check=true rows skip that batch-owned ping
• C2C claiming is not exposed through the public API; use the End Customer Portal

12) Edge diagnostics

xyte-cli edge claim-status --tenant <tenant-id> --proxy-id <proxy-id> --device-ip <device-ip>
xyte-cli edge ping --tenant <tenant-id> --proxy-id <proxy-id> --device-ip <device-ip> --plan
xyte-cli edge ping-status --tenant <tenant-id> --proxy-id <proxy-id> --device-ip <device-ip>

Key params:

• edge claim-status and edge ping-status are read-only
• edge ping is a standalone diagnostic command
• batch claim owns its own pre-claim ping for rows that require connectivity verification

13) Upgrade flow

xyte-cli upgrade --check --output json
xyte-cli upgrade --yes --output json

Key params:

• --check dry check
• --yes non-interactive upgrade

14) Action logs and diagnostics

xyte-cli --log-actions --log-actions-path ./logs/xyte-cli.actions.ndjson status --tenant <tenant-id>
xyte-cli logs list --path ./logs/xyte-cli.actions.ndjson --limit 200
xyte-cli logs list --path ./logs/xyte-cli.actions.ndjson --session-id <session-id> --output json
xyte-cli logs show --path ./logs/xyte-cli.actions.ndjson --entry <sessionId>:<seq> --output json
xyte-cli logs show --path ./logs/xyte-cli.actions.ndjson --request-id <request-id> --output json
xyte-cli logs stats --path ./logs/xyte-cli.actions.ndjson

Key params:

• --log-actions lifecycle NDJSON
• logs list --session-id narrows a run
• logs show --entry and logs show --request-id are exact non-interactive lookups

---

Deep Docs

• Getting started
• Commands reference
• Claim devices
• Utility preprocessing
• Agent guidance
• Flow authoring
• Schema contracts