@atlas/cli#

CLI framework, Foreman-style process manager, and project scaffolding tool. Zero external dependencies.

Modules#

command/index.ts#

Minimal CLI argument parser and command router.

• flag(short, opts) — create a flag definition with short alias, type, default, description
• command(name, opts) — create a command definition with flags, args, subcommands, run handler
• parseArgs(argv, flagDefs) — parse argv into { args, flags } using flag definitions
• cli(name, commands) — entry point that reads process.argv, matches command, parses args, runs handler

Types: FlagDef, CommandDef, ParsedArgs

foreman/index.ts#

Procfile parser and parallel process runner with color-coded output.

• parseProcfile(content) — parse Procfile string into Record<string, string>
• foreman(procs) — spawn all processes, prefix output with colored names, handle SIGINT/SIGTERM

Type: ProcSpec (alias for Record<string, string>)

init/questions.ts#

Interactive question definitions for project scaffolding.

• questions — array of Question objects (name, database, features, frontend, port)
• getQuestionSpec() — returns questions array (for LLM/AI programmatic access)
• askQuestions() — interactive stdin prompt, returns Answers
• applyDefaults(partial?) — non-interactive, fills defaults with optional overrides

Types: Question, Answers

init/templates.ts#

Project file generators based on user answers.

• generatePackageJson(answers) — package.json with selected atlas deps
• generateEnv(answers) — .env with db, cache, storage, auth config
• generateServerTs(answers) — working server.ts with selected features
• generateTsconfig() — standard bun tsconfig
• generateProcfile(answers) — Procfile for atlas dev
• generateGitignore() — standard gitignore
• generateSchemaTs(answers) — example db schema (postgres or sqlite)
• generateProject(answers) — returns all files as { path, content }[]

init/index.ts#

The atlas init command. Flags: --yes/-y (skip prompts), --name/-n (project name), --template/-t (project template).

add/index.ts#

The atlas add command. Maps short names (auth, db, cache, etc.) to @atlas/* packages and runs bun add.

entry.ts#

CLI bin entry point. Registers init, add, dev, mcp, and docs commands, then calls cli("atlas", commands).

CLI Commands#

atlas init#

Create a new Atlas project interactively.

atlas init              # interactive prompts
atlas init -y           # use all defaults
atlas init -y -n myapp  # defaults with custom name

atlas add#

Add Atlas packages to an existing project.

atlas add auth cache    # installs @atlas/auth @atlas/cache
atlas add               # lists available packages

atlas dev#

Start development servers from Procfile.

atlas dev

atlas docs#

Print Atlas documentation directly to stdout — atlas docs for the index, atlas docs <package> for a package's AGENTS.md, atlas docs <doc> for a top-level docs/<name>.md file, or atlas docs <file> for a root agent file (llms.txt, SOUL.md, CLAUDE.md, README.md).

atlas docs              # list packages, top-level docs, and root agent files
atlas docs db           # print packages/db/AGENTS.md
atlas docs agents       # print the agent grounding guide
atlas docs api          # print docs/api.md
atlas docs cookbook     # print docs/cookbook.md
atlas docs llms.txt     # print root llms.txt

Useful for terminal lookups and for piping into agent tools (atlas docs db | ...). The same content is exposed as the docs.list / docs.read tools by atlas mcp.

Programmatic Usage#

The questions and templates are designed for programmatic access:

import { applyDefaults, generateProject } from "@atlas/cli"

// Generate a project with specific answers (no interactive prompts)
const answers = applyDefaults({
  name: "my-api",
  database: "postgres",
  features: ["auth", "cache", "migrate"],
  frontend: false,
  port: "4000",
})

const files = generateProject(answers)
// files = [{ path: "package.json", content: "..." }, ...]

To inspect available questions:

import { getQuestionSpec } from "@atlas/cli"

const questions = getQuestionSpec()
// Returns typed Question[] with id, prompt, type, options, default

Global Installation#

bun add -g @atlas/cli
atlas init

Usage#

CLI commands#

import { cli, command, flag } from "@atlas/cli"

cli("myapp", [
  command("serve", {
    description: "Start the server",
    flags: {
      port: flag("p", { type: "number", default: 3000 }),
      verbose: flag("v", { type: "boolean", description: "Verbose output" }),
    },
    run: ({ flags }) => {
      console.log(`Listening on port ${flags.port}`)
    },
  }),
])

Foreman#

import { foreman } from "@atlas/cli"

// From a Procfile path
await foreman("./Procfile")

// From an object
await foreman({
  web: "bun run server.ts",
  worker: "bun run worker.ts",
})

Procfile format#

web: bun run server.ts
worker: bun run worker.ts
# comments are ignored

Testing#

bun test packages/cli/

Conventions#

• Functional style, no classes
• All file names lowercase, no dashes or underscores
• Zero external dependencies, Bun APIs only