> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Utilities

> CLI commands for diagnostics, organization switching, updates, shell completions, and machine-readable schemas.

This page covers the smaller, less-frequently-used commands: `doctor`, `switch`, `update`, `completions`, and `schema`.

## islo doctor

Check the local CLI setup — authentication, configuration, and connectivity to the Islo API.

```bash
islo doctor
```

Run `islo doctor` first when something looks wrong. It surfaces:

* Whether you are logged in (and which method — OAuth or `ISLO_API_KEY`)
* Whether `islo.yaml` (if present) parses cleanly
* Whether the API is reachable from your machine

No flags. Add `--output json` for structured output.

## islo switch

Switch between organizations (tenants) you belong to.

```bash
islo switch
```

Behavior:

1. Prints your current organization.
2. Opens your browser for an OAuth flow that lets you pick a different org.
3. Replaces your stored credentials with the new org's tokens.

There is no inline org picker — selection happens in the browser via Descope. After the flow, run `islo status` to confirm.

## islo update

Update the CLI to the latest version, or install a specific one.

```bash
islo update [options]
```

**Aliases:** `islo upgrade`

| Option             | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `--check`          | Print the current and latest versions; don't install |
| `--version <v>`    | Install a specific version (e.g., `v0.5.0`)          |
| `-f, --force`      | Skip the confirmation prompt                         |
| `--channel <name>` | Release channel: `stable` (default) or `dev`         |

**Examples:**

```bash
islo update                          # Update to latest stable
islo update --check                  # Only check for updates
islo update --version v0.21.0        # Pin to a version
islo update --channel dev            # Track the dev channel
islo update --channel dev --force    # No prompt
```

The command prints the current and latest versions, then downloads and runs `install.sh` from the releases server — the same path a fresh install uses. If you originally installed via `cargo install`, `islo update` skips the auto-update path; use `cargo install` to update instead.

## islo completions

Install or print shell completion scripts.

```bash
islo completions <subcommand>
```

### Install

```bash
islo completions install [--shell <shell>]
```

Adds an `eval "$(islo completions show <shell>)"` line to your shell's rc file (e.g., `~/.zshrc`, `~/.bashrc`). If `--shell` is omitted, the current shell is detected from `$SHELL`. Supported shells: `bash`, `zsh`, `fish`.

```bash
islo completions install              # Auto-detect shell
islo completions install --shell zsh  # Force zsh
```

Open a new terminal (or `source` your rc file) for completions to take effect.

### Show

```bash
islo completions show <shell>
```

Prints the source line for the requested shell to stdout. Use this when you want to wire completions in by hand instead of letting `install` edit your rc file.

```bash
islo completions show bash
islo completions show zsh
```

## islo schema

Output the machine-readable command schema as JSON. Intended for scripts and AI agents that drive the CLI.

```bash
islo schema [command] [--short]
```

| Argument / Option      | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `command` (positional) | Inspect one command. Omit to get a top-level overview with capability groups and recommended workflows. |
| `--short`              | Minified JSON (fewer tokens — useful for LLM prompts)                                                   |

**Examples:**

```bash
islo schema                  # Top-level overview (skills + commands)
islo schema use              # Full args, flags, and examples for `islo use`
islo schema job              # Job CLI surface + full job.toml manifest schema
islo schema factory          # factory line CLI surface + full line.toml schema
islo schema webhook          # ensure_sandbox template schema + webhook CLI surface
islo schema gateway          # Schema for the gateway command tree
islo schema --short          # Minified overview
```

Use this when you want a programmatic source of truth for the CLI surface — it always matches the installed binary, while these docs may lag a release behind. For factory automations, prefer `islo schema factory` / `islo schema job` (OpenAPI `LineManifest` / `JobManifest`). For incoming webhook ensure-sandbox templates, use `islo schema webhook` and compute OpenAPI `IncomingWebhookSandboxTemplate`.