cosmos

From chaos to scalable structure. Cosmos bootstraps Go projects from templates and installs reusable packages with clarity and predictability.

It focuses on explicit decisions, clear structure, and long-term maintainability—so new systems start with the same rigor as production ones.

curl -sSL https://raw.githubusercontent.com/cosmos-toolkit/cosmos-cli/main/scripts/install.sh | sh
Explore

Usage

Interactive mode (recommended)

Run cosmos init with no arguments. Cosmos will prompt for project name, template (built-in or external), module path, and whether to overwrite an existing directory. 

cosmos init

Listing templates & packages

cosmos init --list

Lists every built-in template plus external templates fetched from github.com/cosmos-toolkit/templates, alongside their descriptions. 

cosmos init --list

Need reusable packages? Run cosmos list pkgs to see what is available before installing with cosmos pkg.

Templates cache: ~/.cache/cosmos/templates/_repo. Packages cache: ~/.cache/cosmos/packages/_repo. Refresh with cosmos update or cosmos cache refresh. Set GITHUB_TOKEN for higher API limits.

Commands overview

Command Description
cosmos, cosmos --help Show usage
cosmos version, cosmos -v Show version
cosmos init Interactive wizard (project name, template, module)
cosmos init --list, -l List built-in + external templates
cosmos list templates List external templates (GitHub)
cosmos list pkgs List available packages
cosmos pkg Interactive package installer
cosmos pkg <name> Install package directly
cosmos update, cosmos cache refresh Refresh template & package caches (git pull)

Built-in templates

Three template types are embedded in the CLI and ready to go.

api

HTTP service with handlers, server, and routing

Scaffolds handlers, routing, server setup, and starter folder layout for HTTP services.

worker

Background processing and async jobs

Provides job processors, scheduling hooks, and structure for long-running or asynchronous tasks.

cli

Command-line tool with subcommands

Sets up command parsing, subcommand wiring, and a baseline for developer tooling.

External templates & contracts

Additional templates live in github.com/cosmos-toolkit/templates. Each subdirectory (e.g. api-hexagonal) is one template, listed via the GitHub API and described in a root manifest.yaml.

Templates are fetched with git sparse checkout and cached under ~/.cache/cosmos/templates/_repo. Descriptions shown in cosmos init --list come from templates.<name>.description in the manifest. 

cosmos list templates

Packages

Install reusable packages into an existing project directly from github.com/cosmos-toolkit/packages. Run the command from the project root (where go.mod lives). 

cosmos pkg

Cosmos rewrites imports to your module, applies dependencies declared in each package’s manifest, and caches source code under ~/.cache/cosmos/packages/_repo.

Preview what is available with cosmos list pkgs before installing.

Why Cosmos exists

New projects often start with unclear boundaries, inconsistent structure, and shortcuts that become permanent.

Cosmos exists to turn that initial chaos into intentional structure. It provides an explicit, predictable starting point so systems can grow without friction, keeping every decision visible instead of hidden behind generators or frameworks.

The result is a CLI that bootstraps projects the way experienced engineers do it by hand: deterministic, explicit, and focused on long-term maintainability.

What Cosmos does

  • →Initializes projects from built-in templates (api, worker, cli) or external templates on GitHub.
  • →Installs reusable packages from github.com/cosmos-toolkit/packages, rewriting imports automatically.
  • →Validates project names, module paths, and template/type choices before generating anything.

Cosmos is a system initializer, not a framework. It is explicit by default, deterministic, and designed for teams that care about clarity and maintenance over flashy scaffolding.