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
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed cmd_. |
object | string | Always "command". |
name | string | Starts with /, then lowercase letters, digits and dashes, e.g. /release-notes. Unique in the workspace. |
description | string | Shown in the composer’s command menu. |
prompt | string | What the agent should do when someone runs it. Text typed after the command is appended. |
bindings | object | What running it uses: agent (name), skills (names), workflow_id and factory_id. Each is null or empty when unbound. |
agents | string[] | Agents that can be asked to run it. Empty means every agent. |
created_at | string | When 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.
{
"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
https://api.duun.ai/v1/commands Returns the workspace’s slash commands by name, including ones installed from Explore. Needs commands:read.
Query parameters
-
agentstring Optional -
Only commands bound to this agent.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom 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){
"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
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
-
namestring Required -
Starts with
/then lowercase letters, digits and dashes, e.g./release-notes. -
descriptionstring Required -
Shown in the composer's command menu. Max 120 characters.
-
promptstring Required -
What the agent should do when someone runs it.
-
bindingsobject Optional -
agent,skills,workflow_id,factory_id. Aworkflow_idmust belong tofactory_idwhen both are set. -
agentsstring[] 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"},
){
"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 conflictwith codename_takenwhen another command has the name.400 invalid_requestwithparam: "name"when the name doesn’t start with/or uses other characters.400 invalid_requestwithparam: "bindings.workflow_id"when the workflow isn’t in the bound factory.
Retrieve a command
https://api.duun.ai/v1/commands/{command} Returns one command. Pass its id, or its name without the slash. Needs commands:read.
Path parameters
-
commandstring 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
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
-
commandstring Required -
The command's id or name without the slash.
Body parameters
-
namestring Optional -
A new name, starting with
/. -
descriptionstring Optional -
Shown in the command menu.
-
promptstring Optional -
What the agent should do.
-
bindingsobject Optional -
Merged. Set a field to
null(or[]forskills) to unbind it. -
agentsstring[] 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"]}){
"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
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
-
commandstring 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"){ "id": "cmd_hotfix9a", "object": "command", "deleted": true }