# Handover CLI connection verification

Use this checklist before allowing a person or agent to publish, continue, or
review protected context.

## 1. Install the public CLI

Requirements: Node.js 22.13 or newer.

```bash
npm install --global handover-sh@0.1.3
handover --version
```

Expected version: `0.1.3`.

## 2. Authenticate one named identity

Create a scoped service agent in Handover for unattended work. Do not reuse a
person's credential across agents.

```bash
handover login
```

The credential is entered interactively and stored in the user's configuration
directory with user-only permissions. It must never appear in source control,
prompts, logs, comments, or handover artifacts.

For an ephemeral environment:

```bash
export HANDOVER_URL="https://handover.sh"
export HANDOVER_TOKEN="hnd_..."
```

## 3. Run the read-only diagnostic

Human-readable:

```bash
handover doctor
```

Machine-readable:

```bash
handover doctor --json
```

Required checks:

- `ok` is `true`.
- `endpoint` is the intended Handover API.
- `identity.type` is the expected person or service agent.
- `identity.organizationName` and `identity.workspaceName` match the task.
- `identity.role` and `identity.scopes` are no broader than required.
- `contextRead.ok` is `true`.
- no credential appears in stdout or stderr.

The command makes only two protected reads: the active identity and one
limited context-list request. It does not create or modify a handover.

## 4. Classify a failure at the first broken layer

| Failure | Likely layer | Action |
| --- | --- | --- |
| Cannot reach endpoint | URL, DNS, proxy, or service | Verify `HANDOVER_URL` from the agent's runtime |
| Unauthorized | Missing, expired, or revoked credential | Authenticate or rotate that named identity |
| Wrong person or agent | Saved connection or secret selection | Run `handover logout`, then authenticate explicitly |
| Wrong company or workspace | Membership or principal configuration | Correct the identity boundary |
| Missing scopes | Service-agent grant | Grant only the required scope |
| Read denied | Item sharing or workspace policy | Fix access; do not substitute a broader credential |

Stop on failure. Never fall back to another person's credential.

## 5. Verify exact protected context

Use a known, non-sensitive marker:

```bash
handover search "continuity-check-UNIQUE_MARKER" --json
handover show <handover-id> --json
```

Confirm the current revision, attached artifact, open review feedback, and
expected next action. A successful connection alone does not prove that the
principal can see the intended record.

## 6. Test a permitted write

Only continue when the returned role and scopes permit it:

```bash
handover create \
  --title "CLI continuity check UNIQUE_MARKER" \
  --note "Created only for an attributable end-to-end verification." \
  --objective "Prove that another authorized identity can resume this record." \
  --next "Retrieve the exact revision from a second identity."
```

Read the created handover back and record its canonical ID. Keep it restricted
unless a person explicitly selects broader access.

## 7. Prove cross-identity continuity

From another authorized person or service agent:

1. Run `handover doctor`.
2. Receive only the canonical link or unique marker, not the original chat.
3. Retrieve the handover and exact revision.
4. State the objective, current state, evidence, and next action.
5. Continue with the expected revision ID.
6. Verify that history attributes each revision to the correct identity.

## Pass criteria

- The endpoint and authenticated principal are explicit.
- Company, workspace, role, and scopes match the intended boundary.
- A protected context read succeeds.
- A permitted write is attributable to the correct identity.
- Another authorized identity retrieves the exact evidence without transcript
  replay.
- The second actor creates a separate immutable revision.
- Revoking either credential blocks that principal without changing the other.
- No credential is printed, committed, or stored in an artifact.

## References

- Guide: https://handover.sh/guides/test-mcp-server-connection-cli
- Install: https://handover.sh/install
- CLI source: https://github.com/44-pixels/handover-mcp/tree/main/cli
- MCP authorization: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization