Commands

Create, update and delete slash commands and bind them to an agent, skills, a factory or a workflow through the Duun API.

On this page

A slash command is a saved prompt anyone can run from the composer by typing its name, like /release-notes or /triage. A command can be bound to an agent, skills, and a factory or workflow, so running it always starts the same kind of work. See Slash commands for how they behave in the app.

The command object

FieldTypeDescription
idstringUnique id, prefixed cmd_.
objectstringAlways "command".
namestringStarts with /, then lowercase letters, digits and dashes, e.g. /release-notes. Unique in the workspace.
descriptionstringShown in the composer’s command menu.
promptstringWhat the agent should do when someone runs it. Text typed after the command is appended.
bindingsobjectWhat running it uses: agent (name), skills (names), workflow_id and factory_id. Each is null or empty when unbound.
agentsstring[]Agents that can be asked to run it. Empty means every agent.
created_atstringWhen the command was created.

When a command is bound to a workflow, running it starts a run of that workflow with the prompt as the run’s first message. Without a workflow, it runs as a conversation with the bound agent.

Command
{
  "id": "cmd_relnotes",
  "object": "command",
  "name": "/release-notes",
  "description": "Draft release notes from PRs merged since the last tag",
  "prompt": "Gather the PRs merged since the last release tag. Group them as Added, Changed and Fixed. Write one plain sentence per change, link each PR, and leave out internal refactors.",
  "bindings": {
    "agent": "writer",
    "skills": ["voice-and-tone"],
    "workflow_id": null,
    "factory_id": "fac_platform"
  },
  "agents": [],
  "created_at": "2026-10-20T13:00:00Z"
}

Endpoints

List commands

GET https://api.duun.ai/v1/commands

Returns the workspace’s slash commands by name, including ones installed from Explore. Needs commands:read.

Query parameters

agent string Optional

Only commands bound to this agent.

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from the previous page.

curl https://api.duun.ai/v1/commands \
  -H "Authorization: Bearer $DUUN_API_KEY"
import Duun from "@duun/sdk";

const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });

for await (const cmd of duun.commands.list()) {
  console.log(cmd.name, cmd.description);
}
from duun import Duun

client = Duun()

for cmd in client.commands.list():
    print(cmd.name, cmd.description)
Response
{
  "object": "list",
  "data": [
    { "id": "cmd_relnotes", "object": "command", "name": "/release-notes", "description": "Draft release notes from PRs merged since the last tag" },
    { "id": "cmd_standup", "object": "command", "name": "/standup", "description": "What shipped, what's running and what's waiting on people" },
    { "id": "cmd_triage", "object": "command", "name": "/triage", "description": "Label, size and route new issues" }
  ],
  "has_more": false,
  "next_cursor": null
}

List items are full command objects; the example is trimmed.

Create a command

POST https://api.duun.ai/v1/commands

Adds a slash command to the workspace. It appears in everyone’s command menu at once. Needs commands:write.

Body parameters

name string Required

Starts with / then lowercase letters, digits and dashes, e.g. /release-notes.

description string Required

Shown in the composer's command menu. Max 120 characters.

prompt string Required

What the agent should do when someone runs it.

bindings object Optional

agent, skills, workflow_id, factory_id. A workflow_id must belong to factory_id when both are set.

agents string[] Optional

Agents that can be asked to run it. Omit for every agent.

curl https://api.duun.ai/v1/commands \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "/hotfix",
    "description": "Start a hotfix run with a mandatory reviewer",
    "prompt": "Fix the problem described below with the smallest safe change and a regression test.",
    "bindings": { "factory_id": "fac_platform", "workflow_id": "wf_hotfix21b" }
  }'
const hotfix = await duun.commands.create({
  name: "/hotfix",
  description: "Start a hotfix run with a mandatory reviewer",
  prompt: "Fix the problem described below with the smallest safe change and a regression test.",
  bindings: { factory_id: "fac_platform", workflow_id: "wf_hotfix21b" },
});
hotfix = client.commands.create(
    name="/hotfix",
    description="Start a hotfix run with a mandatory reviewer",
    prompt="Fix the problem described below with the smallest safe change and a regression test.",
    bindings={"factory_id": "fac_platform", "workflow_id": "wf_hotfix21b"},
)
Response
{
  "id": "cmd_hotfix9a",
  "object": "command",
  "name": "/hotfix",
  "description": "Start a hotfix run with a mandatory reviewer",
  "prompt": "Fix the problem described below with the smallest safe change and a regression test.",
  "bindings": { "agent": null, "skills": [], "workflow_id": "wf_hotfix21b", "factory_id": "fac_platform" },
  "agents": [],
  "created_at": "2026-11-15T11:40:00Z"
}

Errors worth handling:

  • 409 conflict with code name_taken when another command has the name.
  • 400 invalid_request with param: "name" when the name doesn’t start with / or uses other characters.
  • 400 invalid_request with param: "bindings.workflow_id" when the workflow isn’t in the bound factory.

Retrieve a command

GET https://api.duun.ai/v1/commands/{command}

Returns one command. Pass its id, or its name without the slash. Needs commands:read.

Path parameters

command string Required

The command's id (cmd_relnotes) or name without the leading slash (release-notes).

curl https://api.duun.ai/v1/commands/release-notes \
  -H "Authorization: Bearer $DUUN_API_KEY"
const cmd = await duun.commands.retrieve("release-notes");
cmd = client.commands.retrieve("release-notes")

The response is a command object.

Update a command

PATCH https://api.duun.ai/v1/commands/{command}

Changes a command. Send only the fields you want to change; bindings is merged. Needs commands:write.

Path parameters

command string Required

The command's id or name without the slash.

Body parameters

name string Optional

A new name, starting with /.

description string Optional

Shown in the command menu.

prompt string Optional

What the agent should do.

bindings object Optional

Merged. Set a field to null (or [] for skills) to unbind it.

agents string[] Optional

Replaces the list.

curl -X PATCH https://api.duun.ai/v1/commands/release-notes \
  -H "Authorization: Bearer $DUUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bindings": { "skills": ["voice-and-tone", "docs"] } }'
await duun.commands.update("release-notes", {
  bindings: { skills: ["voice-and-tone", "docs"] },
});
client.commands.update("release-notes", bindings={"skills": ["voice-and-tone", "docs"]})
Response
{
  "id": "cmd_relnotes",
  "object": "command",
  "name": "/release-notes",
  "bindings": { "agent": "writer", "skills": ["voice-and-tone", "docs"], "workflow_id": null, "factory_id": "fac_platform" }
}

The response is the full command object; the example is trimmed.

Delete a command

DELETE https://api.duun.ai/v1/commands/{command}

Removes the command from everyone’s command menu. Runs it started aren’t affected. Needs commands:write.

Path parameters

command string Required

The command's id or name without the slash.

curl -X DELETE https://api.duun.ai/v1/commands/hotfix \
  -H "Authorization: Bearer $DUUN_API_KEY"
await duun.commands.delete("hotfix");
client.commands.delete("hotfix")
Response
{ "id": "cmd_hotfix9a", "object": "command", "deleted": true }

    Type to search the docs, help center and blog.