agent-share CLI reference

agent-share is the standalone Go CLI for Agent Share — share to and from your coding agents from anywhere. It logs you in over OIDC, wires Claude Code's ./.mcp.json to a remote inbox, lists and manages your agents, runs the stdio MCP/channel servers, receives iPhone screen mirrors over AirPlay, and mints inbound webhook URLs.

The CLI source lives in src/agent-share/ (a separate Go module from the server). Releases are published for every platform; since 1.14.0 they auto-publish to the agentics.dk store. See the releases page.

Synopsis

agent-share <command> [options]

login        Log in to an Agent Share server (OIDC loopback browser flow)
init         Wire ./.mcp.json to your PERSONAL inbox
register     Create + name an inbox, wire a pinned channel, print the A2A card
card         Print A2A connection details (Azure Foundry inputs) for this inbox
agents       List your agents (status + last heartbeat)   [aliases: list, ls]
disable      Hide an agent from the share picker (inbox kept)
enable       Un-hide a disabled agent
mcp          Run the stdio MCP server (agent mode, or --personal proxy)
channel      Run as a Claude Code channel (research preview)
install      Wire ./.mcp.json (mcp tools, channel mode, or aspire)
airplay      Receive iPhone screen mirroring (AirPlay) on this Wi-Fi
webhook      Manage inbound-webhook URLs                   [alias: webhooks]
version      Print the CLI version                         [--version, -v]
help         Show usage                                    [-h, --help]

Global environment variables

OIDC login requests scopes openid profile email offline_access.

Config/credential dir. The default is ~/.agent-share. When USE_ASPIRE is truthy (or install aspire is used), the CLI uses ~/.agent-share-aspire instead so a local login never clobbers your production credentials. Override the location with AGENT_SHARE_HOME.

login

Logs in to an Agent Share server using an OIDC loopback (browser) flow, then saves the refresh token, your sub, and your display name to the credential store. After saving, it sanity-checks the token against GET /api/agents.

Endpoints: OIDC authorize/token at the issuer; verifies with GET /api/agents.

Stale or dead refresh tokens auto re-login inline when running on a TTY; non-interactively the CLI prints copy-paste re-login instructions (shipped 1.15.0).

init

Wires ./.mcp.json to run agent-share mcp --personal — your personal inbox. From Claude Code you can then read your phone shares, share.send to buzz your phone via Web Push, and register sub-agents. Also drops the agent-share SKILL.md.

Requires a prior login. No token is written to the file — auth uses your stored login (auto-refreshed).

register [NAME]

One-command setup: enroll and name an inbox, wire a self-contained ./.mcp.json running agent-share channel pinned to that inbox, then print the A2A card plus the channel launch line.

NAME is a free-text positional that may contain spaces; flags may appear in any position (e.g. register "My Agent" --dir x). If omitted, a name is suggested.

Endpoint: POST /api/agents/enroll.

The wired entry embeds AGENT_SHARE_SERVER and AGENT_SHARE_TOKEN in its env (the inbox bearer). There is a clobber guard: if the folder already has an agent-share MCP, the CLI prompts to replace it in place or spin up a --dir working folder; a non-TTY run refuses rather than overwrite.

agent-share register "Backend Agent" --role "API refactor" --dir backend

agents

Lists the owner's agents with a status dot (online / idle / offline), a disabled flag, relative last-active, role, and id.

Aliases: list, ls.

Endpoint: GET /api/agents.

disable / enable

Hide an agent from the share picker (the inbox is kept) or un-hide it. The target is resolved by exact id or by a unique case-insensitive name.

agent-share disable "Backend Agent"
agent-share enable 0f3a9c12

Endpoints: POST /api/agents/{id}/disable, POST /api/agents/{id}/enable.

mcp

Runs the stdio MCP server.

Default (agent) mode auto-registers this workspace as an agent on startup, heartbeats every 2 minutes for the session's lifetime, and exposes the tools:

No token is stored in the MCP config — auth comes from your login (auto-refreshed).

--personal (also -personal) connects to your personal hosted inbox as the owner, exposing the share.* tools. This is what init wires.

The hosted /mcp server exposes a different tool set (share.list, share.get, share.get_frame, share.peek_text, share.mark_received, share.delete, share.send, agent.*, webhook.*). See the channels/inbox guide for read-state semantics — reading does not mark an item received.

channel

Research preview. Claude Code channels are a Claude-Code-specific feature (Claude Code v2.1.80+) whose contract is subject to change. This command is not the shipped pull-inbox path.

Runs as a Claude Code Channel: a hand-rolled JSON-RPC stdio server that long-polls open items and pushes A2A tasks and phone shares as notifications/claude/channel events, so an idle session wakes. It advertises the experimental.claude/channel capability.

Channel tools: complete, mark_received, get_agent_card, register, list, send_to_agent.

Token resolution is the same as card (AGENT_SHARE_TOKEN / stored login). Launch a session against it with:

claude --dangerously-load-development-channels server:agent-share --dangerously-skip-permissions

card

Prints the A2A connection details (the inputs an Azure Foundry agent needs) for this inbox, plus the AGENT_SHARE_TOKEN/AGENT_SHARE_SERVER you would use to launch a matching channel.

Endpoint: GET /api/agent/card. Token resolution matches channel.

install [channel]

Wires ./.mcp.json to run agent-share mcp (pull-style agent tools), or agent-share channel when you pass channel, and drops SKILL.md. No secret is written to the file — auth is your stored login.

agent-share install            # wires `agent-share mcp`
agent-share install channel    # wires `agent-share channel`

install aspire [resource]

Wires ./.mcp.json to the local Aspire server instead of production. The resource defaults to share. The CLI runs aspire describe <resource> --format Json, prefers PUBLIC_BASE_URL (falling back to the loopback URL), pulls OIDC_ISSUER, and sets a separate AGENT_SHARE_HOME (~/.agent-share-aspire) so a local login doesn't clobber prod.

agent-share install aspire share

airplay

Live iPhone screen-mirror receiver (shipped 1.17.0). The iPhone AirPlays to a pure-Go receiver that decrypts FairPlay to raw H.264.

STREAM mode (default) posts each mirror's Annex-B H.264 to the inbox via chunked POST /api/streams (Content-Type video/h264); the first byte creates a live stream item and EOF ends it. FILE mode (--out) instead writes mirror-<id>.h264 locally.

Constraint: the iPhone and PC must be on the same Wi-Fi — discovery is mDNS link-local and does not work over Tailscale.

agent-share airplay --name "Poul's Mac"

webhook (alias: webhooks)

Manages inbound-webhook URLs for your account. Inbound events land in the inbox as kind=event shares carrying fields like provider, severity, status, resource, and environment.

Availability. Webhooks are ADR-dated 2026-06-18 — post-1.17.0 and unreleased at the time of writing. Check the releases page before relying on them in a published build.

webhook create (aliases: add, new)

Mints a webhook URL and prints the full URL once.

Endpoint: POST /api/inbox/webhooks. The printed URL looks like:

https://share.agentics.dk/api/inbox/webhook/coolify?secret=whk_...

webhook list (alias: ls)

Lists your webhook URLs with secrets masked.

Endpoint: GET /api/inbox/webhooks.

webhook revoke <id> (aliases: rm, delete)

Revokes a webhook by id.

Endpoint: POST /api/inbox/webhooks/{id}/revoke.

version / help

agent-share version      # also --version, -v  → prints "agent-share <version>"
agent-share help         # also -h, --help

.mcp.json secrets

./.mcp.json is project-scoped Claude Code config. Whether it carries a secret depends on how it was wired:

Feature timeline

Capabilities by the version that shipped them (from the CHANGELOG):

Webhooks (agent-share webhook) are ADR-dated 2026-06-18 — post-1.17.0 and unreleased at the time of writing.