microagent delete
Last updated: 2026-08-15
microagent delete <name> [<name>...] [--reason <text>] [--yes] [--force] [--state-dir <dir>]delete removes the workspace record and its on-disk artifacts (rootfs,
bundles, state file). The removal is permanent - to shut a workspace down
and keep it, use halt instead.
Several names delete in one call, with one confirmation for the whole batch and a result line per workspace. A failure on one workspace does not stop the others, and the exit status reports whether any failed. Slow deletions show a single delayed completed/total counter for the batch. Fast deletions remain quiet; JSON output contains only the typed batch result.
By default, delete asks for confirmation. If the workspace is running, the
prompt becomes “Stop and delete it?”. Either --yes or --force skips the
prompt; on a running workspace, --yes stops it gracefully before deleting,
while --force kills it instead.
Delete is idempotent: deleting a workspace that does not exist (or was
already deleted) exits 0, so retried teardown never fails on “already
gone”. The output still reports “did not exist; nothing deleted” (JSON:
"deleted": false), which makes a typo’d name or an unexpanded shell glob
visible. No confirmation is asked in that case.
Examples
Section titled “Examples”Delete a workspace (asks for confirmation):
microagent delete researchDelete several at once (one prompt for the batch):
microagent delete research scratch demoNon-interactive cleanup:
microagent delete research --yesmicroagent delete research -yForce-delete a running workspace:
microagent delete research --forceLower-level form:
microagent delete agent-1 --state-dir /tmp/microagentCommon flags:
--yes/-y- skip the confirmation prompt in scripts; stops a running workspace before deleting--force/-f- also skips the prompt, but kills a running workspace instead of stopping it
The complete set:
| Flag | Description |
|---|---|
--name <name> |
Workspace name; positional name is also accepted |
--id <id> |
Workspace ID alias for --name |
--reason <text> |
Opaque reason recorded as each lifecycle event’s purpose |
--state-dir <dir> |
State directory holding the workspace record (default ~/.microagent/) |
--backend <name> |
Backend identity override |
--supervisor <path> |
Override the installed host backend supervisor path |
--yes, -y |
Confirm deletion without prompting |
--force, -f |
Skip the prompt and kill a running workspace before deleting |
See global flags for --output/--json/--supervisor.
Exit status
Section titled “Exit status”delete exits 0 when every named workspace is removed or was already
absent. It exits nonzero when any workspace cannot be removed, or when a
running workspace cannot be stopped or killed first. A non-interactive run
without --yes or --force that would require confirmation also fails
rather than prompting blindly.