ATLASdocs
Field guide/@wess/atlas/cli

@wess/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 selecting exact coordinated Atlas libraries and their required peers
  • 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 validates public module names and installs the facade, selected implementation libraries, and the required external peers using the release catalog. It accepts narrow entries such as auth/password and db/postgres.

migrate/index.ts#

The atlas migrate command. migrate/run.ts holds the action logic (runMigrate(args, { dir, url }, deps), deps injectable for tests), migrate/target.ts holds parseTarget(DATABASE_URL) and checkName. @wess/atlas/migrate and the db driver are resolved from the consuming project at run time (like mcp); install with atlas add migrate db/postgres or db/sqlite.

entry.ts#

CLI bin entry point. Registers init, add, check, dev, migrate, mcp, docs, and skills 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/password cache    # installs only selected libraries and required peers
atlas add               # lists available packages

atlas check#

Check an application's manifests, Bun lockfile, installed Atlas links, source imports, and TypeScript aliases. Atlas facade and backing libraries must use the same exact stable version. Local paths, legacy aliases, and links outside node_modules fail the check. Run bunx --package https://github.com/wess/atlas/releases/download/v0.5.1/wess-atlas-cli-0.5.1.tgz atlas check in application CI after a frozen install.

atlas migrate#

Run SQL migrations from ./migrations (--dir/-d overrides). Reads DATABASE_URL: postgres:// or postgresql:// uses the postgres driver, anything else is a sqlite path (./app.db, sqlite:./app.db, file:./app.db). new needs no database.

atlas migrate up               # apply pending migrations
atlas migrate down             # roll back the most recent one
atlas migrate status           # applied / pending per migration
atlas migrate new add_users    # create migrations/<yyyymmddhhmmss>_add_users/{up,down}.sql

Errors (missing DATABASE_URL, unknown action, bad name, module not installed) print a one-line message and exit 1.

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.

atlas skills#

List, print, or install the agent skills shipped with the CLI.

atlas skills                                   # list them
atlas skills atlasserver                       # print one
atlas skills install                           # copy all into .claude/skills
atlas skills install --dir .agents/skills atlasdb

Programmatic Usage#

The questions and templates are designed for programmatic access:

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

// 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 "@wess/atlas/cli/scaffold"

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

Global Installation#

bun add -g https://github.com/wess/atlas/releases/download/v0.5.1/wess-atlas-cli-0.5.1.tgz
atlas init

Usage#

CLI commands#

import { cli, command, flag } from "@wess/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 "@wess/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

Scaffolds use public @wess/atlas/* imports. The distributed package includes the CLI bin and all ten templates. atlas init creates a local .env with fresh 32-byte authentication/state secrets and mode 0600 (owner-only; .env.example keeps the default mode); templates reject short auth secrets. Custom servers use the same connection, route, guard, and admin APIs as the library.

The /cli root exports only command parsing and process management. Import project generation from /cli/scaffold and documentation commands from /cli/docs. The CLI executable resolves optional MCP from the consuming project; run atlas add mcp before atlas mcp.

Canonical sourcepackages/cli/AGENTS.md
Type to search guides and package references.