Create your app

This guide takes you from an empty machine to a working Talos application with its first domain. You install the CLI, scaffold the project, then build a Movie resource: a module, an entity, a repository, and a controller. You can build that resource in two ways: by running the CLI commands yourself, or by handing a single detailed prompt to your AI agent. Both produce the same result.

Prerequisites

The CLI runs on Bun. Install it first:

curl -fsSL https://bun.sh/install | bash

Verify the installation:

bun --version

Step 1: Install the CLI

Install the binary

Install the talos binary with the official installer for your platform. It downloads the latest release, adds it to your PATH, creates the oo alias, and installs shell completions.

macOS / Linux
Windows

curl -fsSL https://raw.githubusercontent.com/ooneex/talos/main/packages/cli/scripts/install.sh | bash

powershell -c "irm https://raw.githubusercontent.com/ooneex/talos/main/packages/cli/scripts/install.ps1 | iex"

Verify

Restart your shell, then confirm the CLI is available and check its version. -h / --help and -v / --version are shortcuts for the help and version commands:

talos help        # or: talos -h, talos --help
talos version     # or: talos -v, talos --version

Stay up to date

Upgrade to the latest release at any time. upgrade checks GitHub and only reinstalls when a newer version is available:

talos upgrade

See Installation for custom install locations, pinning a specific version, shell completions, and uninstalling.

Step 2: Create the application

Scaffold a complete application with app:create. Run it with no flags to be prompted for the name and destination:

talos app:create

Or pass them directly:

talos app:create --name=MovieApp --destination=movie-app

This creates the app and shared modules, the entrypoint, the shared database, roles, Docker files, and config, then installs all dependencies. You are also offered optional CI/CD files for GitHub, GitLab, or Bitbucket. During scaffolding the CLI runs git init and then asks “Install the commit-msg hook?” (enabled by default). Accepting it installs a git hook that keeps your commit messages consistent — see The commit message hook below. It then asks “Add skills for which assistants?”, a multiselect of coding assistants (Claude and Codex enabled by default) — see Step 3 for what those skills unlock. Move into the project and start it:

cd movie-app
talos app:start

app:start brings up the Docker services defined by the app module (when an api or microservice module is running), then runs every discovered api, microservice, spa, storybook, and swagger module concurrently. The api and microservice modules serve their entrypoint with hot reload, while spa, storybook, and swagger modules run their dev server.

The environment file is generated at .env.yml in the project root. Edit it to point at your database, Redis, and other services before starting.

Start only part of the app

Pass --modules or --packages (aliases of one another) with a comma-separated list of module names to narrow what runs. Without either flag, every discovered module runs — regardless of type (api, microservice, spa, storybook, or swagger).

talos app:start                          # every runnable module
talos app:start --modules=app            # only the app module
talos app:start --modules=billing,admin  # only the named modules
talos app:start --packages=billing       # --packages is an alias for --modules

The shared Docker stack still comes up first whenever at least one selected module is an api or microservice (the types that depend on it); spa, storybook, and swagger modules don’t need it. When you’re done, stop the app:

talos app:stop

app:stop brings down the app module’s shared Docker stack with docker compose down. The running module processes (spa dev servers and hot-reloaded entrypoints) stop when you interrupt the app:start process with Ctrl+C. It accepts the same --modules/--packages name filter as app:start, but only to decide whether an api or microservice module is in scope — it always brings down the app module’s own Docker stack, not a named module’s individual docker-compose.yml:

talos app:stop --modules=app   # bring down the app module's Docker stack

The commit message hook

When you accept the “Install the commit-msg hook?” prompt during app:create, the CLI installs a native git commit-msg hook into your repository. It runs on every commit, validates the message, and aborts the commit with a list of errors if the message doesn’t conform. There is no husky or commitlint dependency — the check is built into the CLI and self-contained. The hook is a small script at .git/hooks/commit-msg that simply delegates to the CLI:

#!/usr/bin/env sh
# Talos commit-message linter — installed by `talos commitlint:init`.
exec talos commitlint:check --file "$1"

What it enforces

Messages must follow the conventional-commit format type(scope): Subject:

Type — lower-case and one of build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.
Scope — required, lower-case, and a valid scope (see below). Combine several with ,, /, or \.
Subject — non-empty, must start with an upper-case letter, and must not end with a period.
Header — the whole type(scope): Subject line is limited to 100 characters.
Body — separated from the header by a blank line, with each line limited to 100 characters.

Merge, revert, and fixup! / squash! / amend! messages are always accepted so automated commits pass through.

git commit -m "feat(movie): Add release year column"   # ✓ passes
git commit -m "added movie stuff"                        # ✗ rejected: no type/scope, lower-case subject

Scopes are discovered automatically. Valid scopes are the literal common plus the name of every directory under packages/* and modules/* that contains a package.json. When you scaffold a new module like movie, movie becomes a valid scope with no config to edit.

Managing the hook

Install or reinstall it at any time (for example on a repo cloned without the hook):
talos commitlint:init
Bypass it for a single commit with git’s built-in flag:
git commit --no-verify -m "wip"

Project structure

app:create generates a Bun workspace organized around modules. Every module under modules/<name>/ owns its own controllers, services, repositories, entities, and config: a self-contained vertical slice of your domain.

movie-app/
├── modules/
│   ├── app/                    # API module — the application entrypoint
│   │   ├── src/
│   │   │   ├── AppModule.ts     # Registers controllers, middlewares, cron jobs, events
│   │   │   ├── index.ts         # Boots the App (routing, cache, rate limit, loggers)
│   │   │   └── OnAppStart.ts    # Startup hook
│   │   ├── tests/
│   │   ├── var/
│   │   ├── app.yml              # Module config (type: api)
│   │   ├── docker-compose.yml
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── shared/                  # Shared module — cross-cutting code
│       ├── src/
│       │   ├── databases/
│       │   │   └── SharedDatabase.ts
│       │   ├── SharedModule.ts  # Aggregates entities from every module
│       │   └── roles.yml        # Role definitions
│       ├── tests/
│       ├── package.json
│       └── tsconfig.json
├── var/                        # Runtime data (gitkept)
├── .dockerignore
├── .env.yml                    # Environment configuration
├── .gitignore
├── biome.jsonc                 # Formatter and linter config
├── package.json                # Workspace root (scripts, workspaces)
├── README.md
└── tsconfig.json               # Root config with module path aliases

Each business domain you add (like Movie) becomes its own module alongside app and shared, registered automatically into AppModule.

Step 3: Build your first resource

With the app scaffolded, build the Movie domain. Choose the path that fits how you work: the CLI walks you through each artifact, while the AI prompt produces the whole slice in one pass.

AI prompt
CLI commands

Your project includes AI skills for every create command. Initialize them once, then give your agent a single prompt and it drives the module:create, entity:create, repository:create, and controller:create skills for you.Skills for the assistants you selected during app:create are already scaffolded. If you skipped that prompt or need to add another assistant, run it directly:

talos agent:skills:create

Then copy this prompt into your agent:

Build a complete `Movie` domain in my Talos application using the
Talos CLI create skills. Follow the project's module conventions and
generate the matching tests for every artifact.

1. Module
   - Create a `movie` module and register it into the `app` destination.

2. Entity — `Movie`, mapped to the `movies` table, with these columns:
   - `title`        varchar(255), required, indexed
   - `slug`         varchar(255), required, unique
   - `description`  text, nullable
   - `releaseYear`  int, required
   - `durationMin`  int, nullable          (runtime in minutes)
   - `rating`       numeric(3,1), nullable (0.0–10.0)
   - `genre`        varchar(50), nullable
   - `isPublished`  boolean, default false
   Keep the generated audit columns (id, timestamps, soft delete).

3. Repository — `Movie`
   - Keep the generated CRUD methods.
   - Enable the `q` text search in `find` to match on `title`.
   - Add `findBySlug(slug: string)` returning a single movie or null.

4. Controllers under `/movies`, each thin, validated, and restricted to
   `ROLE_USER`:
   - `MovieList`    GET    /movies        list with pagination + `q` search
   - `MovieRead`    GET    /movies/:id    fetch one by id
   - `MovieCreate`  POST   /movies        validate the payload, persist
   - `MovieUpdate`  PUT    /movies/:id    partial update
   - `MovieDelete`  DELETE /movies/:id    soft delete

Wire payload, params, query, and response validation on each route, keep
the controllers delegating to the repository, and run the formatter,
linter, and tests when done.

The agent scaffolds each artifact with the CLI, fills in the columns, methods, routes, and validation, and writes the tests, producing the same module structure shown in the CLI tab.

Run the create commands in order. Each one scaffolds the class plus a mirrored test file and registers it into the module.

Create the module

Generates modules/movie/ and registers it into AppModule (and its entities into SharedModule).

talos module:create --name=movie --destination=app

See module:create.

Create the entity

Scaffolds a TypeORM entity. The Entity suffix is appended automatically, so --name=Movie produces MovieEntity, mapped to the movies table.

talos entity:create --name=Movie --module=movie --table-name=movies

Open modules/movie/src/entities/MovieEntity.ts and add your columns. See entity:create.

Create the repository

Scaffolds a repository with full CRUD over the entity.

talos repository:create --name=Movie --module=movie

See repository:create.

Create the controller

Generates an HTTP controller, registers it in the module’s controllers array, and configures the route. Repeat with different names, paths, and methods for each endpoint.

talos controller:create \
  --name=MovieList \
  --module=movie \
  --is-socket=false \
  --route-name=movie.list \
  --route-path=/movies \
  --route-method=get

See controller:create.

Resulting module structure

Either path produces the same module, a complete vertical slice for the Movie domain:

modules/movie/
├── src/
│   ├── controllers/
│   │   └── MovieListController.ts   # Route config + handler
│   ├── entities/
│   │   └── MovieEntity.ts           # TypeORM entity → movies table
│   ├── repositories/
│   │   └── MovieRepository.ts       # CRUD over MovieEntity
│   └── MovieModule.ts               # Registers controllers, entities, …
├── tests/
│   ├── controllers/
│   ├── entities/
│   ├── repositories/
│   └── MovieModule.spec.ts
├── movie.yml                        # Module config
├── package.json
└── tsconfig.json

Next steps

CLI commands

Explore every generator: services, events, migrations, seeds, and more.

Controllers

Learn routing, validation, and role-based access in depth.

Entities

Model your data with TypeORM entities and the shared database.

Repositories

Query and persist data with the repository pattern.

Getting Started

AI

Framework

Command Line

Create your app

Prerequisites

Step 1: Install the CLI

Step 2: Create the application

Start only part of the app

The commit message hook

What it enforces

Managing the hook

Project structure

Step 3: Build your first resource

Resulting module structure

Next steps

CLI commands

Controllers

Entities

Repositories

​Prerequisites

​Step 1: Install the CLI

​Step 2: Create the application

​Start only part of the app

​The commit message hook

​What it enforces

​Managing the hook

​Project structure

​Step 3: Build your first resource

​Resulting module structure

​Next steps

CLI commands

Controllers

Entities

Repositories

Prerequisites

Step 1: Install the CLI

Step 2: Create the application

Start only part of the app

The commit message hook

What it enforces

Managing the hook

Project structure

Step 3: Build your first resource

Resulting module structure

Next steps