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, and no control characters. 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 because membership follows the folder, not its name. The response contains the renamed folder without agent_count; renaming neither changes nor reports the count. Read it 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
none	`unknown action "<action>" ...`, `name is required`, `new_name is only valid with action "rename"`, or `action "rename" requires new_name`: the arguments do not fit the action.	Fix the arguments the message names.
none	`no folder named "<name>" ...`: no folder of yours has that name, for `rename` or `delete`.	The message lists the folders you do have.
`INVALID_ARGUMENT`	The name is malformed: not 1-76 UTF-8 bytes, leading or trailing whitespace, or a control character.	Pick a name that fits the rules.
`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

Integrations

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