project, workspace, session
These commands manage projects (engineering directories), workspaces (the directory tree a conversation reads and writes), and session lists on the Host. Paths are paths on the Host machine. A running Host and DIMO_TOKEN are required.
A project registers an engineering tree. A workspace is the directory bound to a conversation (project root or a Git worktree). A session card is a board entry. Dialogue content and turns use the conversation commands.
npx dimo project list
List every project on this Host.
npx dimo project list
npx dimo project list --jsonNo extra flags. The response is an array of projects, each with id, name, repository paths, and related fields. Use id with npx dimo project show, npx dimo project delete, and npx dimo session create --project.
npx dimo project show
Read one project, including its repositories (the git repo IDs used as --repo on npx dimo git).
npx dimo project show --id PROJECT_ID--id is required. An unknown ID returns a Host error.
npx dimo project create
Register a project on the Host. With only a name, the Host creates or binds a directory by its own rules. With --path, that path is registered as a repository.
npx dimo project create --name demo
npx dimo project create --name demo --path /home/you/src/demo--name is required. --path is optional and must be a Git directory the Host can access, or a directory it will initialize. When --path is set, the repository display_name matches the project name and git_repo_path is that path. The response is the new project JSON; store id.
The path is on the Host machine. Running the CLI on another computer still points at the Host’s filesystem.
npx dimo project delete
Delete the project and its conversations and workspace data. Permanent.
npx dimo project delete --id PROJECT_ID--id is required. An in-progress conversation may cause the delete to fail; the Host returns the error. Confirm the target with npx dimo project show first. The Host response records what happens to the Git repository on disk.
npx dimo workspace list
List workspaces. A workspace is the directory bound to a conversation: the project root folder, or a Git worktree cut from that folder.
npx dimo workspace list
npx dimo workspace list --project PROJECT_IDWithout --project, every workspace on the Host is listed. With --project, only that project’s trees. Each item includes a workspace id, used as --workspace on npx dimo conversation create and npx dimo session list.
New worktrees are created in the desktop New session → New workspace flow, then discovered with this command. This CLI has no separate “create worktree” action.
npx dimo workspace show
Read one workspace’s path, branch, and parent project.
npx dimo workspace show --id WORKSPACE_ID--id is required. Use it to confirm which directory tree a conversation will read and write.
npx dimo session list
List session cards on a workspace (the board entries).
npx dimo session list --workspace WORKSPACE_ID--workspace is required. The response includes session ID, title, agent, and status. Missing --workspace raises Missing required --workspace.
npx dimo session show
Read one session card.
npx dimo session show --id SESSION_ID--id is required. Difference from npx dimo conversation show: this command is the board/catalog record; npx dimo conversation show is dialogue output and turn status. In most cases the two IDs name the same conversation; trust the returned JSON.
npx dimo session create
Create a session card. Two shapes.
By workspace (the workspace must already exist):
npx dimo session create \
--workspace WORKSPACE_ID \
[--agent AGENT_ID] \
[--title TITLE] \
[--prompt TEXT]By project (the Host may pick the project’s default workspace):
npx dimo session create \
--project PROJECT_ID \
[--workspace WORKSPACE_ID] \
[--agent AGENT_ID] \
[--title TITLE] \
[--prompt TEXT]--title, --prompt, and --agent are all optional. To bind an agent and send the first message immediately, npx dimo conversation create is the direct path. This command fits creating a board entry from a project catalog. The ID in the JSON can be passed to npx dimo conversation send.
With --project, the project-create API is used and --workspace may be omitted. With only --workspace (no --project), the workspace-create API is used. Missing both raises Missing required --workspace.
npx dimo session delete
Delete a session record. The Host decides whether an in-progress session can be removed; failures print an error.
npx dimo session delete --id SESSION_ID--id is required. This removes the Host session record. The workspace directory and Git history stay on disk.