# 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://docs.openservicedirectory.org/guides/discover-support.md).

## Search for support

```bash
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 the active registries listed in the registry directory. It combines candidates while preserving their entries and source registries. You choose which candidate to use. Add `--json` for structured output, and inspect coverage warnings or conflicts before choosing a candidate.

To search one registry instead, use `--target <url>` or set `OSD_REGISTRY_URL`. An explicit `--target` takes precedence over the environment variable. The target is a registry base URL:

```bash
osd search "Example Air cancelled flight rebooking" \
  --target https://registry.example/
```

## 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
```

Directory search returns candidate records in `results`. Each contains the complete OSD `entry`, its source registries, and a separate `verification` annotation. The annotation's `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 |
| `not_checked` | The candidate was not checked before the directory search's verification deadline |

To verify a candidate separately, save its `entry` object from the search results 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. Default directory search puts each complete entry in `.results[].entry`.

A successful `search --verify` does not mean every registry responded or every candidate verified. A completed `osd mcp --call` does not mean the tool succeeded: inspect coverage, each verdict, and each tool result.

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