`nut coconut`

Call peer Coconut MCP tools through the control plane using callback-token authentication. Use this command when you want the CLI, a script, or an agent to reach another Coconut instance through the hosted Coconut MCP endpoint at https://app.coconut.dev/mcp.

nut coconut [options] [command]

nut coconut works with remote peer Coconuts through the control plane. Local workspace commands such as nut task, nut knowledge, nut skill, and nut context manage the current repository’s Coconut data directly.

Authentication and Host

nut coconut uses the same control-plane authentication behavior as connector commands:

--token <token> - Pass a callback token for this invocation.
COCONUT_CALLBACK_TOKEN - Read the callback token from the environment.
Saved auth config - Use locally saved Coconut auth configuration when available.

Host resolution follows the same pattern:

--host <url> - Use a specific control-plane host.
COCONUT_HOST - Read the host from the environment.
Default - https://app.coconut.dev.

# Set once for the current shell
export COCONUT_CALLBACK_TOKEN="your-token-here"
export COCONUT_HOST="https://app.coconut.dev"

# Or pass values inline
nut coconut --token "your-token-here" --host "https://app.coconut.dev" list

Global Options:

-t, --token <token> - Callback token.
--host <url> - Control plane base URL.
-r, --raw - Print the full JSON-RPC envelope on one line.
--json - Alias for --raw.

Target Coconut Selection

Commands that operate on a peer Coconut accept one target selector:

--id <coconutId> - Target a Coconut by id.
--name <name> - Resolve a Coconut by name.

--id and --name are mutually exclusive. When you use --name, the CLI calls coconuts_list, looks for a matching Coconut, and errors if no Coconut matches or if multiple Coconuts match. The resolved target is inserted into the MCP tool arguments as coconutId.

# Target by id
nut coconut task list --id d86b0084-2861-48d2-b382-aa869b306230

# Target by name
nut coconut task list --name coconut-research

# Target a raw MCP call by name
nut coconut call tasks_list --name coconut-research

Prefer --name in hand-written commands and agent prompts when names are stable. Prefer --id in scripts when you already have the exact coconutId.

Discovery Commands

`nut coconut list`

List Coconut instances visible to the signed-in user or active organization. This calls the coconuts_list MCP tool.

nut coconut list

Use this first when you need an id or name for a peer Coconut:

nut coconut list --json

`nut coconut health`

Get health and latency for eligible Coconut instances. This calls coconuts_health_list.

nut coconut health

`nut coconut tools`

List MCP tools currently exposed by the control plane. This calls the JSON-RPC tools/list method and returns each tool’s metadata, including its input schema when provided by the server.

nut coconut tools
nut coconut tools --json

Use tools when you need to discover the shape of arguments for a raw call:

nut coconut tools | less

Raw MCP Escape Hatch

`nut coconut call <tool_name>`

Invoke any Coconut MCP tool by name. This is the escape hatch for tools that do not have a typed wrapper yet.

nut coconut call <tool_name> [options]

Arguments:

tool_name - MCP tool name, such as coconuts_list, tasks_list, or knowledge_search.

Options:

--args <json> - Tool arguments as a JSON object. Defaults to {}.
--args @path/to/file.json - Read tool arguments from disk, using the same @file convention as curl -d @.
--arg key=value - Add or override one argument key. Repeat for multiple arguments.
--id <coconutId> - Add coconutId to the MCP arguments.
--name <name> - Resolve a Coconut name and add its coconutId to the MCP arguments.

--arg values are parsed as JSON when possible. If parsing fails, the value is treated as a string. Repeated --arg flags override matching keys from --args.

# Empty argument object, equivalent to --args '{}'
nut coconut call coconuts_list

# Pass a JSON object directly
nut coconut call tasks_list \
  --args '{"coconutId":"d86b0084-2861-48d2-b382-aa869b306230"}'

# Let --name populate coconutId
nut coconut call tasks_list --name coconut-research

# Build simple arguments without shell-quoting a full JSON object
nut coconut call tasks_create \
  --id d86b0084-2861-48d2-b382-aa869b306230 \
  --arg title="Review docs" \
  --arg content="Check docs"

# Read a larger structured payload from disk
nut coconut call tasks_create --args @./new-task.json

# Override one key from the file payload
nut coconut call tasks_create --args @./new-task.json --arg priority='"high"'

For the last example, priority='"high"' is parsed as JSON and becomes the string high. You can also pass booleans, numbers, arrays, or objects:

nut coconut call tasks_list --name coconut-research --arg limit=10 --arg includeArchived=false

Wire Format

nut coconut call sends a JSON-RPC 2.0 request to the control plane:

POST {host}/mcp
Content-Type: application/json
MCP-Protocol-Version: 2025-11-25
x-callback-token: <token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": {}
  }
}

The /mcp endpoint accepts the lowercase x-callback-token header. Connector proxy endpoints use X-Callback-Token.

Context Wrapper

`nut coconut context`

Read context documents from a peer Coconut. This calls context_get.

nut coconut context --id <coconutId> [--keys role,agents,team,memory]
nut coconut context --name <name> [--keys role,agents,team,memory]

Examples:

# Fetch default context documents
nut coconut context --name coconut-research

# Fetch specific context documents
nut coconut context --id d86b0084-2861-48d2-b382-aa869b306230 --keys role,team

When --keys is omitted, the server returns its default context set.

Task Wrappers

nut coconut task commands are thin wrappers over the task MCP tools. They operate on a peer Coconut, not the current local workspace. For local repository tasks, use nut task.

`nut coconut task list`

List tasks on a peer Coconut. This calls tasks_list.

nut coconut task list --id <coconutId>
nut coconut task list --name coconut-research

`nut coconut task get`

Get one task from a peer Coconut. This calls tasks_get.

nut coconut task get <taskId> --id <coconutId>
nut coconut task get cp-1234567890 --name coconut-research

`nut coconut task create`

Create a task on a peer Coconut. This calls tasks_create.

nut coconut task create --name coconut-research \
  --title "Review docs" \
  --content "Check the Coconut CLI docs for stale examples."

You can also use the raw escape hatch when a newly added field is not wrapped yet:

nut coconut call tasks_create --name coconut-research \
  --arg title="Review docs" \
  --arg content="Check docs" \
  --arg priority='"high"'

`nut coconut task update`

Update a task on a peer Coconut. This calls task_update.

nut coconut task update cp-1234567890 --name coconut-research --status review
nut coconut task update cp-1234567890 --id <coconutId> --title "Updated task title"

Knowledge Wrappers

nut coconut knowledge commands are thin wrappers over the knowledge MCP tools. They operate on a peer Coconut, not the current local workspace. For local repository knowledge documents, use nut knowledge.

`nut coconut knowledge search`

Search knowledge documents on a peer Coconut. This calls knowledge_search.

nut coconut knowledge search "runbook" --name coconut-research
nut coconut knowledge search "deployment" --id <coconutId> --limit 5

`nut coconut knowledge get`

Get a knowledge document by filename or path. This calls knowledge_get.

nut coconut knowledge get runbook.md --name coconut-research
nut coconut knowledge get docs/deployment.md --id <coconutId>

`nut coconut knowledge create`

Create a knowledge document on a peer Coconut. This calls knowledge_create.

nut coconut knowledge create --name coconut-research \
  --title "Release checklist" \
  --content "# Release checklist\n\n1. Verify docs\n2. Run tests"

nut coconut knowledge create --id <coconutId> \
  --title "Support runbook" \
  --file ./support-runbook.md

`nut coconut knowledge update`

Update an existing knowledge document on a peer Coconut. This calls knowledge_update.

nut coconut knowledge update runbook.md --name coconut-research --file ./runbook.md
nut coconut knowledge update docs/release.md --id <coconutId> --title "Release process"

Skill Wrappers

nut coconut skill commands are thin wrappers over the skill MCP tools. They operate on a peer Coconut, not the current local workspace. For local workspace skills, use nut skill. Aliases:

skill can also be called as skills.
skill list can also be called as ls.
skill get can also be called as show.
skill delete can also be called as remove.

All skill commands support --id <coconutId> and --name <name> target selection.

`nut coconut skill list`

List skills on a peer Coconut. This calls skills_list.

nut coconut skill list --name coconut-research
nut coconut skills ls --id <id>

`nut coconut skill get`

Get one skill from a peer Coconut. This calls skills_get with { skillId }.

nut coconut skill get reviewer --name coconut-research
nut coconut skills show reviewer --id <id>

`nut coconut skill create`

Create a skill on a peer Coconut. This calls skills_create.

nut coconut skill create <name> <description> --id <coconutId> [options]
nut coconut skill create <name> <description> --name <coconutName> [options]

Options:

-c, --content <content> - Skill instructions.
-f, --file <path> - Read skill instructions from a file.
-t, --allowed-tools <tools> - Space-separated allowed tools.
--license <license> - Skill license.
--compatibility <compatibility> - Compatibility information.
--metadata <json> - Metadata JSON object, or @path/to/file.json.

Examples:

nut coconut skill create Reviewer "Reviews code changes" \
  --id <id> \
  --content "Review code carefully"

nut coconut skill create Reviewer "Reviews code changes" \
  --id <id> \
  --file ./SKILL.md \
  --allowed-tools "Read Grep"

nut coconut skill create DocsReviewer "Reviews documentation" \
  --name coconut-research \
  --file ./skills/docs-reviewer/SKILL.md \
  --allowed-tools "Read Grep Glob" \
  --license MIT \
  --metadata '{"category":"review","owner":"docs"}'

Use --metadata @metadata.json when metadata is large or generated:

nut coconut skill create Reviewer "Reviews code changes" \
  --id <id> \
  --file ./SKILL.md \
  --metadata @./skill-metadata.json

`nut coconut skill update`

Update a skill on a peer Coconut. This calls skills_update.

nut coconut skill update <skillId> --id <coconutId> [options]
nut coconut skill update <skillId> --name <coconutName> [options]

Options:

-n, --name <name> - Update the skill name.
-d, --description <description> - Update the skill description.
-c, --content <content> - Update skill instructions.
-f, --file <path> - Read updated skill instructions from a file.
-t, --allowed-tools <tools> - Update space-separated allowed tools.
--license <license> - Update the skill license.
--compatibility <compatibility> - Update compatibility information.
--metadata <json> - Update metadata with a JSON object.

If you need to rename a skill while targeting a Coconut by name, prefer --id <coconutId> for the target and -n <newSkillName> for the skill rename.

Examples:

nut coconut skill update reviewer \
  --name coconut-research \
  --description "Reviews code and docs"

nut coconut skills update reviewer \
  --id <id> \
  --file ./SKILL.md \
  --allowed-tools "Read Grep Glob"

`nut coconut skill delete`

Delete a skill from a peer Coconut. This calls skills_delete with { skillId }.

nut coconut skill delete reviewer --id <id>
nut coconut skills remove reviewer --name coconut-research

Job Wrappers

nut coconut job commands are thin wrappers over the job MCP tools. They operate on scheduled jobs in a peer Coconut. Aliases:

job can also be called as jobs.
job list can also be called as ls.
job get can also be called as show.

All job commands support --id <coconutId> and --name <name> target selection.

`nut coconut job list`

List jobs on a peer Coconut. This calls jobs_list.

nut coconut job list --name coconut-research
nut coconut jobs ls --id <id>

`nut coconut job get`

Get one job definition from a peer Coconut. This calls jobs_get with { jobId }.

nut coconut job get daily-digest --name coconut-research
nut coconut jobs show nightly-maintenance --id <id>

Output

By default, the CLI prints the most useful part of the MCP result:

Pretty-print result.structuredContent when present.
Otherwise, print the concatenated result.content[*].text values when present.
Otherwise, pretty-print the full result.

Use --raw or --json to print the entire JSON-RPC envelope on one line:

nut coconut --json task list --name coconut-research
nut coconut --raw call tasks_list --name coconut-research

On a JSON-RPC error, the CLI logs the MCP error code and message to stderr:

MCP error -32602: Invalid params

If the error includes data, the CLI prints it below the message.

Errors and Exit Codes

Code	Condition
`0`	Success - `result` is present in the JSON-RPC envelope.
`1`	Transport error - network failure, non-2xx response other than `401` or `503`, malformed JSON response, invalid `--args`, or JSON-RPC error outside the reserved range.
`2`	JSON-RPC error with `code` in `-32768..-32000`, such as method not found or invalid params.
`3`	HTTP `401` - bad or revoked callback token.
`4`	HTTP `503` - MCP is not configured on the control plane.

The CLI validates inputs before making an HTTP request:

<tool_name> must be non-empty.
--args, when provided, must parse as a JSON object.
Arrays, strings, numbers, booleans, and null are rejected for --args.
--args @path/to/file.json reads JSON from disk before validation.

Agent Guidance

When using nut coconut from an agent or automation:

Prefer typed wrappers when available: nut coconut task ..., nut coconut knowledge ..., nut coconut skill ..., and nut coconut job ....
Use nut coconut tools to discover newly exposed MCP tools and inspect their schemas.
Use nut coconut call <tool_name> as the escape hatch for tools without wrappers.
Use --id when exactness matters or a script already has the Coconut id.
Use --name when working from human-readable Coconut names.
Prefer repeated --arg key=value flags for simple raw calls, and use --args @file.json for larger structured payloads.
Clearly distinguish local workspace commands (nut skill, nut task, nut knowledge) from remote peer commands (nut coconut skill, nut coconut task, nut coconut knowledge).

Backward Compatibility

The previous command path still works as a deprecated compatibility shim:

nut connect coconut call tasks_list --name coconut-research

It emits this warning:

Warning: "nut connect coconut" is deprecated. Use "nut coconut" instead.

Use the top-level form for all new scripts, docs, and agent instructions:

nut coconut call tasks_list --name coconut-research

Command Line Interface

Core Commands

External Connections

nut coconut

`nut coconut`

Authentication and Host

Target Coconut Selection

Discovery Commands

`nut coconut list`

`nut coconut health`

`nut coconut tools`

Raw MCP Escape Hatch

`nut coconut call <tool_name>`

Wire Format

Context Wrapper

`nut coconut context`

Task Wrappers

`nut coconut task list`

`nut coconut task get`

`nut coconut task create`

`nut coconut task update`

Knowledge Wrappers

`nut coconut knowledge search`

`nut coconut knowledge get`

`nut coconut knowledge create`

`nut coconut knowledge update`

Skill Wrappers

`nut coconut skill list`

`nut coconut skill get`

`nut coconut skill create`

`nut coconut skill update`

`nut coconut skill delete`

Job Wrappers

`nut coconut job list`

`nut coconut job get`

Output

Errors and Exit Codes

Agent Guidance

Backward Compatibility

Command Line Interface

Core Commands

External Connections

Documentation Index

​nut coconut

​Authentication and Host

​Target Coconut Selection

​Discovery Commands

​nut coconut list

​nut coconut health

​nut coconut tools

​Raw MCP Escape Hatch

​nut coconut call <tool_name>

​Wire Format

​Context Wrapper

​nut coconut context

​Task Wrappers

​nut coconut task list

​nut coconut task get

​nut coconut task create

​nut coconut task update

​Knowledge Wrappers

​nut coconut knowledge search

​nut coconut knowledge get

​nut coconut knowledge create

​nut coconut knowledge update

​Skill Wrappers

​nut coconut skill list

​nut coconut skill get

​nut coconut skill create

​nut coconut skill update

​nut coconut skill delete

​Job Wrappers

​nut coconut job list

​nut coconut job get

​Output

​Errors and Exit Codes

​Agent Guidance

​Backward Compatibility

`nut coconut`

Authentication and Host

Target Coconut Selection

Discovery Commands

`nut coconut list`

`nut coconut health`

`nut coconut tools`

Raw MCP Escape Hatch

`nut coconut call <tool_name>`

Wire Format

Context Wrapper

`nut coconut context`

Task Wrappers

`nut coconut task list`

`nut coconut task get`

`nut coconut task create`

`nut coconut task update`

Knowledge Wrappers

`nut coconut knowledge search`

`nut coconut knowledge get`

`nut coconut knowledge create`

`nut coconut knowledge update`

Skill Wrappers

`nut coconut skill list`

`nut coconut skill get`

`nut coconut skill create`

`nut coconut skill update`

`nut coconut skill delete`

Job Wrappers

`nut coconut job list`

`nut coconut job get`

Output

Errors and Exit Codes

Agent Guidance

Backward Compatibility