Skip to Content
AdunemDocs
GuidesCLI referenceHelp

shared, share and call

Use an agent that someone shared with you: save its key, see its tools, and call them from the terminal or a script.

When someone shares an agent with you, you get either an email invite or a share key that starts with amsh_. These commands let you use it from the terminal:

  • adunem share add saves a key on this machine.
  • adunem shared shows the agent, its tools and how many calls you have left.
  • adunem call calls one of its tools and prints the result.

You can also use shared agents in adunem chat and on the Shared with me page. See Use a shared agent for the guide.

Agents shared to your email, rather than by key, show up in adunem chat and adunem share list once you are signed in. The commands below that call a tool need a key: a saved one, or one you provide.

Which key is used

shared and call pick the key like this, in order:

  1. The ADUNEM_SHARE_KEY environment variable, if set and you did not pass --share.
  2. The saved key named by --share <alias>.
  3. The only saved key, if you have exactly one. With several, you must pass --share.
  4. A hidden prompt for the key, if you are at a terminal.

A key is never accepted as a command-line argument, so it does not end up in your shell history or in process lists. A saved key is only ever sent to the Adunem address it was saved for.

share

Saves, lists and removes share keys on this machine. The keys themselves are stored in your operating system's keyring.

share add

adunem share add <alias> [--gateway <url>]

aliastextrequired

A local name for this share, for example bob-agent. Lowercase letters, digits, ., _ and -, up to 63 characters.

--gateway, -gtextdefault: your last gateway

Which Adunem the key belongs to.

It asks for the key without showing it (or reads ADUNEM_SHARE_KEY), and checks the key with Adunem before saving, so a wrong, expired or revoked key is rejected. If you are signed in, it also adds the agent to your account, so it appears under Shared with me everywhere.

$ adunem share add bob-agent
Share key:
✓ saved 'bob-agent': Bob's calculator (share Friends) on https://api.adunem.com
  added to your account: it is under 'Shared with me' in `adunem chat`
→ next: `adunem call <tool> --share bob-agent`, or `adunem chat`

share list

adunem share list [--gateway <url>]

Lists the keys saved on this machine and, when you are signed in, every agent shared with your account, by key or by email invite. It never shows a key.

Saved on this machine:
  bob-agent	Bob's calculator	share Friends	https://api.adunem.com	added 2026-11-10T09:14:02+00:00
Shared with your account on https://api.adunem.com:
  Bob's calculator	Friends	by Bob	online	87 calls left

share remove

adunem share remove <alias>

Deletes the saved key from this machine, and from your account's list if you are signed in.

Removing a key does not revoke the share. Only the person who shared the agent can do that, from their dashboard.

shared

Shows the agent a key gives you access to.

Usage

adunem shared [--share <alias>] [--gateway <url>]

Options

--share, -stextdefault: see Which key is used

The alias of a saved key.

--gateway, -gtextdefault: your last gateway

Which Adunem to use.

What you'll see

agent: Bob's calculator (online)
calls remaining: 87, expires 2026-12-01T00:00:00+00:00
  - calculate: Evaluate a sum, product or average
  - chat: Talk to the agent

It lists each tool you are allowed to use. A note on what the owner can see about your calls is printed to standard error.

call

Calls one tool on a shared agent and prints the result.

Usage

adunem call <tool> [--arg name=value]... [--args <json>] [--timeout <seconds>]
            [--idempotency-key <key>] [--share <alias>] [--gateway <url>]

Options

tooltextrequired

The tool's name, as shown by adunem shared.

--arg, -atextdefault: none

One argument as name=value. Repeat it for more. A value is read as JSON when it is valid JSON (numbers, true, lists and so on), and otherwise as a plain string.

--argstextdefault: none

All arguments as one JSON object. If you also use --arg, the --arg values win.

--timeoutintegerdefault: the agent's own limit

A deadline for the call, in seconds.

--idempotency-keytextdefault: a random one

Reuse the same key to retry a call safely without being charged a second call.

--share, -stextdefault: see Which key is used

The alias of a saved key.

--gateway, -gtextdefault: your last gateway

Which Adunem to use.

Examples

# A tool with simple arguments
adunem call calculate --arg operation=sum --arg numbers='[1,2,3]' --share bob-agent

# The same, as one JSON object
adunem call calculate --args '{"operation":"sum","numbers":[1,2,3]}' --share bob-agent

# Retry-safe: running this twice counts as one call
adunem call generate_report --arg month=2026-10 --idempotency-key report-2026-10

The result goes to standard output, and the call's progress goes to standard error:

invocation 3b1f8c2e-... queued
{
  "result": 6
}

If the agent returns structured data, you get it as formatted JSON, which you can pipe into other tools. Plain text comes back as text.

Exit status and errors

A call that does not succeed exits with code 1, prints call <state> (<code>), and hints at adunem shared. The state is failed, cancelled or timed_out.

MessageMeaning
no saved share keys; run adunem share add <alias>Save a key, set ADUNEM_SHARE_KEY, or run at a terminal to be asked.
several saved shares (a, b); pick one with --shareYou have more than one saved key.
refusing to send it to a different platformThe key was saved for another Adunem address.
call succeeded, but its result is no longer availableResults of shared calls are never stored. If the connection dropped after the call finished, only the status remains, and the call is not run again.
--args is not valid JSON or --arg expects name=valueFix the quoting of your arguments.

On this page