---
name: network-cli
description: Use this skill to operate the Mere Network and voice CLIs for authenticated customer setup, workspace voice bridge configuration, phone/agent workflows, and diagnostics.
---

# Network CLI

Use this skill for requests that touch the standalone network operator CLI or the internal API routes it calls.

## Scope

- CLI entrypoints in `network/cli/*`, especially `mere-network.ts`, `auth.ts`, and `session.ts`.
- Shared product browser auth implemented through `@mere/cli-auth`.
- Control-plane routes in `network/apps/core/src/routes/api/customers/*` and `network/apps/core/src/routes/api/internal/deployments/*`.
- Workspace bridge routes in `network/apps/core/src/routes/api/internal/zerosmb/workspaces/[workspaceId]/*`.

## Base commands and environment

1. Set the base URL:
   - `--base-url` flag or `MERE_NETWORK_BASE_URL`
2. Resolve workspace context for bridge commands:
   - `--workspace` flag or `MERE_NETWORK_WORKSPACE_ID`
3. Token automation overrides remain valid:
   - `--token`
   - `MERE_NETWORK_TOKEN`
4. Prefer `--json` for scriptable reads.
5. Use `completion [bash|zsh|fish]` for shell setup.
6. Use `--query key=value` repeatedly for list or sync filters.
7. Destructive or externally expensive operations require `--yes --confirm <exact-target>`.

## Immediate runbook

1. Build the CLI:
   - `cd /Users/nerd/mere/network && pnpm build:cli`
2. Authenticate:
   - `pnpm exec mere-network -- auth login`
   - `pnpm exec mere-network -- auth whoami`
3. Control-plane reads:
   - `pnpm exec mere-network -- customers list --json`
4. Workspace bridge reads:
   - `pnpm exec mere-network -- --workspace ws_123 calls list --json`
   - `pnpm exec mere-network -- --workspace ws_123 numbers list --json`

## References

- [command-reference.md](references/command-reference.md): command families, key flags, and bridge group layout.
- [route-map.md](references/route-map.md): auth routes plus control-plane and workspace bridge route anchors.
- `/Users/nerd/mere/network/cli/README.md`: concise repo-local CLI overview.

## Auth workflow

1. `auth login` uses the shared product CLI contract from `@mere/cli-auth`.
2. Auth routes live in the nested control-plane app:
   - `network/apps/core/src/routes/api/cli/v1/auth/*`
3. Session file path resolves from the XDG state directory:
   - app name: `mere-network`
   - typical fallback: `~/.local/state/mere-network/session.json`
4. The saved session includes refresh token state, access token, user identity, optional workspace data, and expiry claims.
5. There is no separate user-facing `refresh` command; refresh happens through the shared session helpers.

## Command families

### Control plane

- `customers list|create|update|archive|redeploy|redeploy-all`
- `deployments run --customer <customer-id>`

### Workspace bridge

- `calls list|show|sync|archive|close|analysis|export|audio`
- `interactions list|show|sync|close|read`
- `locations list|create|show|update|delete`
- `scripts list|create|show|update|delete`
- `numbers list|search|show|create|update|delete|pause|resume|route`
- `provider-accounts list|create|show|update|delete|sync`
- `routing default-location|number`

## Validation notes

- Any command outside `auth` requires either a saved dedicated CLI session or an internal token override.
- Workspace bridge commands require a workspace id.
- Mutation commands take JSON payloads through `--json-file`, `--json-input`, `--data-file`, or `--data`.
- `routing number` patches `/numbers/{numberId}/route` while `routing default-location` writes `/default-location`.
- The route files live in `apps/core`, not `network/src`, so repo-wide route lookups must include the nested app path.

## Safe edits

For CLI behavior:
- `network/cli/mere-network.ts`
- `network/cli/auth.ts`
- `network/cli/session.ts`

For shared auth contract behavior:
- `business/packages/cli-auth/*`
- `network/apps/core/src/routes/api/cli/v1/auth/*`

For control-plane and workspace bridge behavior:
- `network/apps/core/src/routes/api/customers/*`
- `network/apps/core/src/routes/api/internal/deployments/*`
- `network/apps/core/src/routes/api/internal/zerosmb/workspaces/[workspaceId]/*`