Howdy

Creating a project

howdy new my_app

howdy new creates a Howdy project in a new folder. The project is a Gleam application with:

  • a themed home page built from Howdy UI, rendered through a layout in src/<project>/layouts/
  • static assets served from priv/public
  • hot reload for development, with the admin at /_howdy and a console ready to attach
  • a test suite, and howdy check to run it
  • AGENTS.md, CLAUDE.md and .claude/skills/, guides for coding agents working on the project

By default it also has a SQLite database with an example todo list: a migration, a todos feature with its record, database operations and a JSON API at /api/todos, and a live todo list on the home page, rendered as a live component.

Project names

The name must be a valid Gleam project name: lowercase letters, digits and underscores, starting with a letter. It cannot be the name of a module that ships with Erlang, such as pg, auth or timer, which the project's own module would replace.

You can give a path instead, and the last segment becomes the project name:

howdy new apps/my_app

Choosing a database

--database picks the database, and sqlite is the default. SQLite needs no setup: the database is a file, created and migrated the first time the app starts.

howdy new my_app --database postgres

--database postgres builds the same project on PostgreSQL. The app connects through a connection pool configured from DATABASE_URL, and the project gets a docker-compose.yml that starts PostgreSQL with a development database and a test database.

howdy new my_app --no-database

--no-database leaves out the database and the todo list, which gives you a page-only project. The howdy create commands that write a table, and the howdy add packages that keep their data in the database, need one, so they do not work in a project made this way.

--database and --no-database cannot be used together.

Leaving things out

howdy new my_app --minimal

--minimal leaves out the dev admin, telemetry and the console, for a project that wants nothing beyond the server.

howdy new my_api --api-only

--api-only makes a JSON backend with no pages. It leaves out Howdy UI, Lustre, the home page, the layouts, the static files and the HTML 404 page, and serves a health check at /health instead. With a database it keeps the todos JSON API. Packages added later follow suit: howdy add auth in such a project adds the JSON API without the sign-in pages.

howdy new my_app --no-agents

--no-agents leaves out AGENTS.md, CLAUDE.md and .claude/skills/.

What happens

howdy new works through these steps, and shows its progress as it goes:

  1. It checks that gleam is installed, and warns you if erl is missing.
  2. It writes the project files.
  3. It formats them with gleam format.
  4. It downloads the dependencies with gleam deps download.
  5. It prints what to do next.

Downloading the dependencies needs a network connection and Git. Pass --skip-deps to leave that step out, and run gleam deps download yourself later:

howdy new my_app --skip-deps

To see the files a command would write without writing them:

howdy new my_app --dry-run --json

Which Howdy release

Every Howdy package in a new project comes from the same release tag, such as ref = "v2.0.0", so they always match and never change under you. By default that is the release the CLI's templates were written for. Pass --howdy to choose another:

howdy new my_app --howdy 2.1.0

A release the templates predate may need changes to the generated code. The project's README says which release it uses and how to upgrade it.

Flags

  • --database sqlite or --database postgres: the database to use. Defaults to sqlite.
  • --no-database: leave out the database and the todo list example.
  • --minimal: leave out the admin, telemetry and the console.
  • --api-only: a JSON backend only, without Howdy UI, pages, layouts or static files.
  • --no-agents: leave out AGENTS.md, CLAUDE.md and .claude/skills/.
  • --howdy 2.1.0: the Howdy release to depend on. Defaults to the one the CLI was written for.
  • --skip-deps: do not run gleam deps download after creating the files.
  • --dry-run: show which files would be created, without writing them.
  • --json: print the result as one JSON object.
  • --plain: print progress as plain lines instead of animating.

Next

Move into the project and start it with howdy dev. If you chose PostgreSQL, start the database first with docker compose up -d. Getting started walks through the first run.