folder

Creates, renames, or deletes a folder in your personal dashboard folder list. The action argument selects which. Equivalent to murmur folder create, murmur folder rename, and murmur folder rm in the CLI. Folders are personal: they change only your own dashboard view, never another user’s. To file agents into a folder, use folder_assign; to read your folder names and what each holds, use spawn_profiles.

Parameters

Name	Type	Required	Description
`action`	string	yes	One of `create`, `rename`, `delete`.
`name`	string	yes	The folder this acts on, by display label. For `create` it is the new folder’s label — 1–76 UTF-8 bytes, no leading or trailing whitespace, no control characters — and a label you already use is rejected. For `rename` and `delete` it must be one of your existing folder names, matched ignoring case.
`new_name`	string	with `rename`	The new display label. Required with `action: rename` and rejected with any other action.

A folder name carries no hierarchy — / is an ordinary character in a label, not a separator.

Actions

`create`

Creates a folder holding no agents. Returns the folder, with agent_count: 0.

{
  "action": "create",
  "name": "Release 4.2"
}

{
  "folder_id": "fld-3b17c9e04ad2",
  "name": "Release 4.2",
  "agent_count": 0
}

`rename`

Changes a folder’s display label. Everything filed under it stays filed: membership follows the folder itself, not its name. Returns the folder as it now reads, with no agent_count — a rename neither changes nor reports it. Read the count from spawn_profiles.

{
  "action": "rename",
  "name": "Scratch",
  "new_name": "Scratch pad"
}

{
  "folder_id": "fld-c07be31d5a94",
  "name": "Scratch pad"
}

`delete`

Deletes the folder. The agents filed under it become unfiled and are otherwise untouched — no agent is stopped, deleted, or altered, and no other person’s view is affected. Returns how many agents were unfiled.

{
  "action": "delete",
  "name": "Release 4.2"
}

{
  "unfiled_agents": 1
}

There is no confirmation step. Read the folder’s agent_count from spawn_profiles first if it matters — that is exactly what the delete will unfile. To undo, create the folder again and re-file the agents with folder_assign.

Response fields

Field	Type	Description
`folder_id`	string	The folder’s stable id, assigned by the server and unchanged by a rename. No tool takes it as input — folders are named by `name`. Returned by `create` and `rename`.
`name`	string	The display label. Returned by `create` and `rename`.
`agent_count`	number	How many agents are filed in the folder. Returned by `create` (always `0`); absent from a `rename`, which does not report a count.
`unfiled_agents`	number	How many agents the delete unfiled. Returned by `delete`.

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	Unknown `action`; missing `name`; `new_name` on an action other than `rename`, or missing on a `rename`; no folder of yours has that name; or the name is malformed.	The error says which. For an unknown name it lists the folders you do have.
`ALREADY_EXISTS`	The name is already used by one of your folders.	Names are unique within your own list, ignoring case. List them with `spawn_profiles` and reuse the existing folder.
`RESOURCE_EXHAUSTED`	You already hold the maximum of 200 folders.	Delete one you no longer use.
`FAILED_PRECONDITION`	The caller has no personal identity to hold folders.	Folders belong to a person; an agent running on a VM has no personal identity and cannot hold them.

folder_assign — file agents under a folder, move them, or unfile them
spawn_profiles — list your folders and their agent counts
spawn — file a new agent at spawn time via folder
murmur folder ls — the CLI’s folder commands

Getting Started

Core Concepts

Guides

Parameters

Actions

`create`

`rename`

`delete`

Response fields

Errors

​Parameters

​Actions

​create

​rename

​delete

​Response fields

​Errors

​Related

Parameters

Actions

`create`

`rename`

`delete`

Response fields

Errors

Related