The cosmonic CLI

cosmonic is the developer command-line tool for Cosmonic Desktop. Use it to scaffold a project and run the build-and-run loop from your terminal. It is the by-hand counterpart to the Builder.

cosmonic is a thin client. Each command sends a request to Cosmonic Desktop's background daemon, and the daemon does the work. Keep Cosmonic Desktop running while you use the CLI. cosmonic is a different program from cosmonicd, the daemon itself. For the daemon and its cosmonicd subcommands, see The cosmonicd Daemon.

You do not install cosmonic yourself. Cosmonic Desktop ships it and puts it on your PATH.

cosmonic new

cosmonic new scaffolds a project from a template that ships inside Cosmonic Desktop. The templates are built in, so scaffolding needs no network and no other tools.

cosmonic new <template> [directory] [--name <name>]

<template> is a template id, such as rust-http. directory is the project directory to create, and it defaults to ./<template>. --name sets the project's display name, and it defaults to the directory name.

The command writes the project and registers it with Cosmonic Desktop, so cosmonic dev works right away in the new directory.

To see the templates you can scaffold from, run:

cosmonic new --list

The set includes HTTP starters in Rust, Go, and TypeScript, a Rust MCP server, and NATS messaging starters in Rust and Go.

Template	Language	What it is
rust-http	Rust	HTTP hello-world on WASI p3 (wasi:http/handler@0.3.0).
go-http	Go	HTTP hello-world built with componentize-go and the wasmCloud Go SDK, on async WASI p3.
ts-http	TypeScript	HTTP hello-world built with jco.
rust-mcp	Rust	MCP server built on the rmcp SDK, served over streamable HTTP.
rust-nats-* and go-nats-*	Rust, Go	NATS messaging starters. Each pattern ships in both languages: core subscriber, request/reply, JetStream consumer, JetStream worker, KV store, KV watcher, and fan-out.

The templates that ship can change between releases. Run cosmonic new --list to see the current set on your machine.

cosmonic dev

cosmonic dev builds the project in the current directory, runs the result on your local host, streams its logs to your terminal, and rebuilds every time you save a file.

cosmonic dev

The workload runs in a namespace called dev and appears in Cosmonic Desktop's Workloads view while the session is live. Press Ctrl-C to stop. The session ends and its dev workload is removed.

The first build compiles the project's dependencies, so it takes longer than later rebuilds. If the build toolchain is not ready the first time you build, Cosmonic Desktop offers to install it. Follow the prompt. The setup runs once.

cosmonic promote

cosmonic promote builds the project, pushes the component image to a registry, and prints a durable Workload manifest you can apply.

cosmonic promote

cosmonic dev runs a live session that disappears when you stop it. cosmonic promote produces a build you can deploy and keep. Reach for it when a component is ready to run as a lasting workload rather than a dev loop.

Options

--socket <path> points the CLI at a specific daemon control socket. By default the CLI finds the socket the same way the daemon does, and it also reads the COSMONIC_SOCKET environment variable. Most people never need this.

Learn the loop

The Handcraft components lesson in Academy, under Next steps, walks through this dev loop from an empty directory to a running, hot-reloading workload. The Builder does the same work through the graphical interface.