# Use the OSD CLI

> Search for support, verify a listing, and connect to a support agent through MCP.

:::note[Not yet available]
The Open Service Directory (OSD) CLI is not yet open source or publicly published. This guide describes how it works so you can evaluate the workflow. Installation instructions will follow its public release.
:::

The OSD CLI gives assistants one interface to search support listings, check brand endorsement, and connect to support agents through MCP. It requires Node.js 22.19 or later.

The examples follow the fictional Example Air scenario in [Discover support](https://cautious-adventure-v6loy75.pages.github.io/guides/discover-support.md).

## Search a registry

```bash
export OSD_REGISTRY_URL=https://registry.example/
osd search "Example Air cancelled flight rebooking" \
  --contract-version 0.3.0 \
  --filter type=application/mcp-server-card+json \
  --page-size 5
```

The CLI queries `--target <url>` if given, then `OSD_REGISTRY_URL`, and otherwise the default registry, `https://directory.zendesk.com`. It returns the registry's candidates and leaves selection to the caller. Add `--json` for structured output.

## Verify and select a candidate

Add `--verify` to check each result against the manifest published on its brand domain:

```bash
osd search "Example Air cancelled flight rebooking" \
  --contract-version 0.3.0 \
  --filter type=application/mcp-server-card+json \
  --verify --json
```

Each result gets a `verification` annotation. Its `verdict` is one of:

| Verdict | Meaning |
| --- | --- |
| `verified` | The complete entry matches an entry in the brand's published manifest |
| `mismatch` | The manifest has the same identifier, but the entry differs. Inspect `diff` |
| `no_match` | The manifest has no entry with the candidate's identifier |
| `unreachable` | The manifest could not be retrieved. Inconclusive, inspect `detail` |
| `malformed` | The manifest could not be validated. Inconclusive, inspect `detail` |
| `invalid` | Invalid candidate data or a local setup error prevented the check |

To check one candidate on its own, save its result object (not the whole response envelope) as `candidate.json`:

```bash
osd verify --candidate candidate.json --contract-version 0.3.0 --json
```

Select a verified candidate that fits the customer's request. Verification confirms the brand published the entry. It does not choose the agent or authorize a support action.

## Connect through MCP

Use the Server Card URL from the verified candidate. `osd mcp` connects and lists the agent's tools:

```bash
osd mcp "https://support.airline.example/server-card.json" --json
```

If the agent requires authorization, an interactive run opens a browser to sign in and caches the credentials. `--no-auth` prevents a new sign-in but still uses cached credentials.

Tool names and arguments come from the agent's tool schemas. If the agent offers a `get_rebooking_options` tool:

```bash
osd mcp "https://support.airline.example/server-card.json" \
  --call get_rebooking_options --args '{"destination":"Singapore"}'
```

`osd mcp` does not check endorsement itself, so verify the entry first. The support agent decides which operations it allows and enforces authentication and permissions. The assistant obtains any confirmation the customer's instructions or its own policy require.

## Use the CLI in scripts

Use `--json`, read diagnostics from stderr, and check exit statuses. A successful `search --verify` does not mean every candidate verified, and a completed `osd mcp --call` does not mean the tool succeeded: inspect each verdict and tool result.

Run `osd --help`, or add `--help` to a command, for all options.