CLI Reference

Every command shipped in the spwn binary.

✨

From zero to running agent.

Three commands. Scaffold a project, boot a world, talk to your agent.

$ spwn init&&$ spwn up&&$ spwn agent neo

⬡

spwn

create realities for things that can think

Project

Project lifecycle

Scaffold, validate, and build a spwn project

initScaffold a spwn project in the current directory checkValidate the project tree against spwn.yaml buildTranspile the project and compile it into a Docker image

Agents

Agent

Compose agents from dependencies; talk, fork, evolve

Lifecycle

agent createCreate a new agent (SOUL.md + 2-layer Mind)agent lsList all agents on this Host agent inspectInspect an agent - composition, memory, world status, history agent talkTalk to a running agent - interactive or one-shot agent rmRemove an agent and its Mind directory agent logsShow the event log for a specific agent

Evolution

agent dreamAnalyze experience, discover patterns, promote playbooks agent sleepConsolidate experience - archive stale files, prune old sessions agent fork[experimental] Clone a Mind from one agent to another

Portability

agent export[experimental] Export an agent as tar.gz agent import[experimental] Import an agent from a tar.gz archive

Deployment

agent deployDeploy an agent to a running world

Worlds

World

Manage the runtime instances declared inline in spwn.yaml

Lifecycle

world createDeclare a new world in spwn.yaml world startStart a world (alias for `spwn up`)world stopStop a world (alias for `spwn down`)world upSpawn a world - an isolated reality for agents world listList declared worlds and their running status world rmRemove a world declaration from spwn.yaml world destroyDestroy a world world renameRename a world (omit name to clear)

Observe

world inspectInspect a running world - agents, workspaces, status world logsShow the event log for a specific world world enterOpen an interactive shell inside a running world

Shared knowledge

world knowledge lsList all knowledge files in a world world knowledge showShow the contents of a knowledge file

Snapshots

world snap saveSave world state as a snapshot world snap lsList all snapshots world snap restoreRestore a world from a snapshot world snap rmRemove a snapshot

Dependencies & authoring

Dependencies

Install, remove, and inspect project dependencies

installInstall a dependency into the project uninstallRemove a dependency from the project inspectShow per-agent composition: deps, skills, hooks

Skills

Author bare-markdown skill files under spwn/skills/

skill edit[experimental] Open a skill file in $EDITOR skill lsList skill files skill newAuthor a new skill file skill rmDelete a skill file skill showDisplay a skill file

Orchestration

Architect

Always-on orchestration daemon

architect logsShow the Architect daemon's event log architect startStart the Architect daemon architect statusShow Architect status - worlds, agents architect stopStop the Architect daemon architect talkTalk to the Architect - ask it to manage worlds and agents

System

Auth

Connect providers and manage credentials

auth checkValidate active credentials against each provider's API auth disableTell spwn not to use this provider, even if creds exist auth enableReverse a previous `disable`auth loginSet up credentials for a provider auth logoutClear stored credentials for a provider auth statusShow every detected credential and which one is active auth usePick which credential method spwn should prefer

Environment

Status and self-update

statusShow the full status of your spwn environment upgradeUpgrade spwn to the latest version