Skip to content
anetos tool and app commands reference

anetos tool and app commands reference

Two command lines: the anetos developer tool (module anetos.dev/anetos/cli), which creates projects and writes code, and your application’s binary, which runs the app and its commands. See Commands and Getting started for walkthroughs.

Installing the tool

CommandUse
go install anetos.dev/anetos/cli/cmd/anetos@latestFor anetos new, before you have a project
go get -tool anetos.dev/anetos/cli/cmd/anetos@latestIn a project: pins the version in go.mod; run it as go tool anetos (projects made by anetos new have it)

Flags may come before or after the other arguments. anetos help <command> (or anetos <command> -h) shows a command’s usage. Exit status: 0 on success, 1 on errors, 2 for bad usage.

anetos new <directory>

FlagDefaultMeaning
--modulethe directory’s nameGo module path
--dbsqlitesqlite, postgres or mysql: the driver in main.go and the DB_* settings in .env
--stackwebweb: pages rendered on the server, with sessions and CSRF protection; api: JSON only, no views, static files or sessions (the API project)
--cssanetosThe web stack’s CSS framework: the components of views/ui and the stylesheet, public/static/app.css. anetos: the starter theme (light and dark, no build step) and components writing its classes; none: components writing plain HTML without classes, and a stylesheet holding only a comment, for your own CSS or a CSS framework; pico, bootstrap, bulma: components writing Pico 2.1.1’s, Bootstrap 5.3.8’s or Bulma 1.0.4’s markup, with the framework’s files as released in public/static/ (and its license), and an app.css for the rest; tailwind: components with Tailwind CSS 4.3.3’s classes, views/ui/tailwind.css and the app.css Tailwind compiles from it (css:build). See Style your app. Refused with --stack=api
--no-agentfalseDon’t write the files coding agents read (AGENTS.md, CLAUDE.md, GEMINI.md, the skills); see agent:install
--skip-installfalseOnly write the files
--replaceA local Anetos checkout, used through replace directives (framework development): the core, the tool, and every driver and plugin module of the checkout, so go get and anetos add take them from it too

The directory must not exist or be empty; its name (letters, digits, - and _, starting with a letter) becomes the app’s name. anetos new . uses the current directory. It writes the project, then runs go get for Anetos, the driver and the anetos tool, all at the tool’s own version (every Anetos module is released with the same version; a development build of the tool takes the latest), pinned as tools with templ, then go tool templ generate and go mod tidy (the api stack has no templ, and runs go run . openapi last, writing openapi.json). With --db=postgres or mysql, create the database before migrate.

The web stack’s files:

PathHolds
main.goanetos.New, i18n.New (the catalogs in locales/), db.Connect, migrate.New, cache.New, queue.New (with workers), events.New, mailer.New, storage.New, schedule.New, web.NewServer, session.New, routes.Register, then ext.Load(app, plugins()), and app.Execute(); //go:generate lines for templ and anetos generate
plugins.goThe plugins, written by anetos add and anetos remove (an empty list at first)
main_test.goTests requesting the home page and a missing page with anetostest
.env, .env.exampleSettings; .env has a fresh APP_KEY (file mode 0600) and stays out of git
.env.testingPostgreSQL and MySQL projects: the test database’s settings (<name>_test)
README.md, .gitignoreHow to run it; what stays out of git
routes/web.goRoutes: the error pages (ErrorPages with views.ErrorPage), assets, and the page group with sessions and CSRF (pages), which make:crud adds its routes to
app/handlers/home.goThe home page handler
app/models/Models (empty at first)
database/migrations/migrations.goThe All migration set and Seeders
database/factories/factories.goThe package for model factories (empty at first)
views/layout.templ, views/home.templtempl layout (<html lang dir> in the request’s locale, hreflang links with APP_LOCALE_STRATEGY=prefix or subdomain, the header with the app’s name and its nav (ui.Header, ui.Nav, and navLink, which marks the current page with web.RouteIs), flash messages, CSRF header for htmx) and home page, its text from the catalog; views/errors.templ: error pages (404, 500…) in the layout
views/ui/The CSS framework’s components, which the layout and the pages of make:crud and make:auth call: ui.go (the types: Variant, Size, Tone, Option, Pages), shell.templ, page.templ, form.templ, data.templ, and with every CSS framework but none, classes.go (the classes of each variant, size and tone), and css.json, the framework’s record (css:use). See the UI components reference
locales/locales.go, locales/en/app.yamlThe translations, embedded: the home page’s English text. Add a language with its folder (locales/bn/app.yaml); see Translations
public/public.go, public/robots.txt, public/static/app.css, public/static/favicon.svgpublic.Files, the web root, served at / by r.Static (robots.txt, allowing every page); public.Assets: the static files and htmx under /assets; the stylesheet (--css; a CSS framework adds the framework’s files); the icon browsers show
Dockerfile, .dockerignoreA container image: anetos build in golang:<go version>, the binary alone in gcr.io/distroless/static-debian12:nonroot (user 65532), /data for the files (and the SQLite database, migrated when the server starts: DB_MIGRATE_ON_START=true), HEALTHCHECK with health:check. See Deploy
deploy/<name>.service, deploy/production.env.exampleA systemd unit (migrations before start, restart on failure, sandboxed) and the production settings to fill in. See Deploy
AGENTS.md, CLAUDE.md, GEMINI.md, .agents/skills/anetos-*/SKILL.md, .claude/skills/anetos-*/SKILL.mdThe files coding agents read: instructions and task guides (skills), as agent:install writes them for every agent; not with --no-agent

The API project

--stack=api writes the same main.go without sessions or templ, plugins.go, .env files, README.md, .gitignore, app/models/, database/, Dockerfile, .dockerignore and deploy/, and in place of the web stack’s routes, handlers, views and static files:

PathHolds
routes/api.goRegister(r): r.UseGlobal(web.JSONErrors) (every error is problem JSON, whatever the client accepts; Return errors) and the group api, /api/v1 with route names api.…, where make:handler suggests routing its handlers; OpenAPI, the API’s description’s openapi.Config
app/handlers/welcome.goGET /api/v1 (api.welcome): a typed handler (web.H) answering WelcomeResponse, {"name", "message"}, the message from the catalog in the request’s language
locales/en/app.yamlThe API’s English messages
main_test.goTests of GET /api/v1, of a missing URL’s problem details, and that openapi.json is up to date (openapi.Check)
openapi.jsonThe API’s OpenAPI 3.1 description, written by go run . openapi (not with --skip-install) and served at /api/v1/openapi.json; main.go calls openapi.Register. See Describe an API with OpenAPI

.env, .env.example and deploy/production.env.example have HTTP_CORS_ORIGINS= (empty: no browser on another origin may call the API; configuration) and no SESSION_DRIVER or APP_LOCALE_STRATEGY. In an API project (routes/api.go and no routes/web.go), make:handler (a typed handler, routed with web.H, answering a struct), make:middleware, make:auth (accounts logging in with API tokens) and make:crud (JSON endpoints) write for the API, and make:admin, which writes pages, refuses.

anetos dev

FlagDefaultMeaning
--addrHTTP_ADDR from .env, else :8080; without a host, on 127.0.0.1 onlyWhere to browse the app (--addr=0.0.0.0:8080 to reach it from other machines, with a warning: the dev server shows build errors and your code’s paths)
--hostlocalhost, *.localhost, IP addresses and APP_URL’s hostAnother host name browsers may use (repeat the flag for more); requests for other names get 403, which stops DNS-rebinding pages from reading the app
-- args…runArguments for the app binary

Run it in the project (any directory under go.mod). On start and on every change it:

  1. runs go tool templ generate (if there are .templ files) and anetos generate, and in a project that uses Tailwind CSS compiles public/static/app.css as css:build does (when Tailwind can’t run, it says why and keeps the app.css there is until it’s restarted),
  2. builds the app into tmp/anetos-dev/,
  3. stops the previous app (interrupt, then kill after 10 s) and starts the new one with HTTP_ADDR set to a free local port,
  4. once the app accepts connections, tells open pages to reload.

Watched: .go (not tests or generated files), .templ, go.mod, go.sum, .env*, everything under public/ and views/ui/tailwind.css (but not a Tailwind project’s public/static/app.css, which the build writes); directories starting with a dot, node_modules and testdata, and tmp, vendor, bin and storage at the project’s root are skipped. Requests during a restart wait for the new version. The proxy adds a small script to HTML pages (not htmx responses, HEAD requests or empty responses) that reloads them; build errors, and an app that stops or doesn’t start, show as an error page until the next change. On Linux the app is stopped even if anetos dev is killed.

anetos build

anetos build [-o file] [--target=os/arch] [--version=v1.2.0] [--cgo] [-- go build flags]

FlagDefaultMeaning
-obin/<name>: the module path’s last element, or the one before a /v2 suffix (.exe for Windows)The binary to write
--targetgo env GOOS/GOARCHThe system to build for: linux/amd64, linux/arm64, windows/amd64… The generators still run on this one
--versionthe version Go records from git: the tag of the commit (v1.2.0), else a pseudo-version (v0.0.0-20261006100000-1a2b3c4d5e6f); (devel) outside a repositoryThe app’s version, for its version command: letters, digits and . + - _ ~ /
--cgofalseBuild with CGO_ENABLED=1 (only for a driver or package that needs cgo; SQLite doesn’t)
-- flags…More go build flags (-tags=…); an -ldflags is added to the build’s own

Run it in the project. It runs go tool templ generate (if there are .templ files), anetos generate and, in a project that uses Tailwind CSS, Tailwind as css:build does (failing if it can’t run), then go build -trimpath -ldflags="-s -w" . with CGO_ENABLED=0, and prints the binary, its system and size (built bin/blog (linux/amd64, 18.3 MB)). Use --target rather than GOOS and GOARCH: with those set, go tool builds the tool itself for the other system, which then can’t run. The binary holds the migrations, views, public/ and locales/: copy it alone. Built in a git repository, it records the commit (and whether files were changed) for version.

anetos make:*

Run anywhere in a project. Existing files are never overwritten (make:auth adds one call to setup in main.go and one line to views/layout.templ; make:crud adds one line to routes/web.go and one to views/layout.templ; make:admin changes setup and adds a line to views/layout.templ; make:admin-resource adds a line to app/admin/admin.go).

CommandWrites
make:handler <Name>app/handlers/<name>.go: a handler type with an Index method; in an API project, a typed Index (for web.H) answering <Name>Response as JSON, its comment routing it in routes/api.go
make:model <Name> [--migration]app/models/<name>.go: a model embedding db.Model, then its typed columns (anetos generate); with --migration, also create_<table>_table
make:migration <name>database/migrations/<YYYY_MM_DD_HHMMSS>_<name>.go: create_posts_table creates a table; add_x_to_posts_table (the last to, from, in or on) gets commented Alter code for that table; other names get empty functions. The timestamp is always after the newest migration’s, so migrations made in the same second keep their order
make:middleware <Name>app/middleware/<name>.go: a func(http.Handler) http.Handler
make:crud <Model> <field:type[:optional|:unique]>...A model with its table and the pages to list, show, create, edit and delete its rows: app/models/<model>.go, a create_<table>_table migration, app/handlers/<table>.go (handlers.<Models>: Index with 20 rows a page, Show, New, Create, Edit, Update, Delete; the form <Model>Input with its validate tags), views/<table>.templ (the list, the page, the form, calling the components of views/ui), routes/<table>.go (routes.<Models>(r): /<path>, the table with - for _, named <path>.index, .new, .create, .show, .edit, .update, .delete, as the handlers), locales/en/<table>.yaml (the pages’ text) and <table>_test.go (its comment shows how to log a user in for pages in make:auth’s loggedIn group); then anetos generate, templ generate and go build ./.... Types: string (255), text, email, int (int64), float (float64), bool, date (anetos.Date). Strings, emails, texts and dates are required unless :optional; :unique (required strings and emails, dates) adds a unique index and the unique rule. Refused: a plural that is the name (News), the tables of the framework and make:auth (users, api_tokens…), the field model, and two fields with one Go name (a_1 and a1). Adds <Models>(pages) at the end of Register in routes/web.go and a navLink to the list at the end of the header’s nav in views/layout.templ: the @ui.Nav block, or before the </nav> of a layout made earlier (else it prints what to add). In a web project without views/ui (made before v0.5), it first writes the components of the CSS framework closest to public/static/app.css (anetos if it has the starter theme’s .card rule, else none), and says so; the stylesheet and the layout are left as they are. Writes nothing if a file or the migration exists or a name is taken. See Add pages for a model. In an API project: JSON endpoints instead, with the model and migration, app/handlers/<table>.go (<Model>Response, the output struct; <Model>Input; <Model>List, the query: page, per_page ≤ 100, sort from a list of columns, exact filters on string, email, int, bool and date fields, so no field may be named page, per_page or sort; Index answering db.Page[<Model>Response], Show, Create with Location, Update (PUT), Delete), routes/<table>.go (/api/v1/<path>, named api.<path>.index…; the create route .Status(201)) and <table>_test.go; <Models>(api) added to Register in routes/api.go (else it prints the call); no views or catalog; then go run . openapi, updating openapi.json (a failure is reported, not fatal). See Add pages for a model
make:agent <Name>app/agents/<name>.go: an ai.Agent with a typed tool; prints how to set up ai.New if main.go doesn’t call it
make:authAccounts, with Google and GitHub login: app/models/user.go (User with disabled_at and session_key, models.Users), app/handlers/auth.go (handlers.Accounts, handlers.SocialUser, handlers.SendVerification and SendPasswordReset), app/mailers/auth.go and views/auth_mail.templ (verification and reset emails), views/auth.templ (pages, and AccountMenu, the header’s account links), routes/auth.go (routes.Auth), auth.go (setupAuth: auth.WithDefaultHomeURL("/dashboard") and sessions.Use(a.Middleware)), auth_test.go, locales/en/auth.yaml, database/factories/users.go (factories.Users, verified users whose password is factories.UserPassword, for tests with anetostest.ActingAs), and a create_users_table migration; the empty SOCIAL_GOOGLE_* and SOCIAL_GITHUB_* settings appended to .env, .env.example and deploy/production.env.example (unless there); then go mod tidy, anetos generate, templ generate and go build ./..., and a setupAuth call in setup after its routes.Register(srv.Router(), sessions) statement (else it prints the call to add), and @AccountMenu() after the layout header’s nav: the @ui.Nav block, or the </nav> line of a layout made earlier (else it prints the line to add). In a web project without views/ui (made before v0.5), it first writes the components, as make:crud does. Writes nothing if one of the files or a create_users_table migration exists, or a name the files declare is taken in its package; removes what it wrote if a write fails. See Add accounts with make:auth. In an API project, JSON endpoints under /api/v1 logging in with API tokens instead: app/models/user.go (without remember_token, pending_email and the preferences), app/handlers/auth.go (handlers.Accounts, typed handlers answering UserResponse, LoginResponse, TokenResponse…), app/mailers/auth.go and app/mailers/auth.html (the emails, an html/template file), routes/auth.go (routes.Auth(r, a), with TokenMiddleware; the account’s routes need a token with every ability, auth.RequireAbilities("*")), auth.go (setupAuth(app, r); refuses to boot without AUTH_CLIENT_URL in production and staging), auth_test.go, locales/en/auth.yaml, database/factories/users.go and the migration; AUTH_CLIENT_URL appended to the settings files; the call after routes.Register(srv.Router()); no templ; then go run . openapi, updating openapi.json. See Add accounts to an API
make:adminThe admin interface, after make:auth; refused in an API project: adds the module anetos.dev/anetos/admin (go get; in a project whose core module is replaced by a checkout, from the checkout), writes admin.go (setupAdmin: roles and permissions with rbac.New and an admin role, unless a Go file of the project already calls rbac.New; then admin.New, the users, admin.Roles, the dashboard (admin.SignUps of the users, admin.QueueHealth, admin.AIUsage if the project tracks AI usage, admin.RecentActivity if it keeps an audit log), admin.Jobs and admin.Schedule (for the app’s queue and scheduler), admin.Activity (with an audit log), the resources of app/admin, and Mount with the pages’ middleware), app/admin/admin.go (Resources, empty), app/admin/users.go (Users: admin.Users for models.User, with the columns and handlers.SendVerification and SendPasswordReset the model and handlers have) and admin_test.go (with rbac.New and make:auth’s tests); adds @admin.Banner() after <body> in views/layout.templ (else it prints the line to add); appends the empty ADMIN_PATH and ADMIN_HOST to .env and .env.example; replaces make:auth’s setupAuth call in setup with one that keeps its *auth.Auth and calls setupAdmin (else it prints the calls to add); then go mod tidy, templ generate and go build ./.... Restores go.mod and go.sum if it fails before writing. See Add an admin panel
make:admin-resource <Model>app/admin/<models>.go: the admin’s resource for a model of app/models, named after the type (Post: posts at /admin/posts, function Posts): columns (the ID and the first four fields the form edits, or the first five without db.Model; created_at), search over its first three string fields, and a form struct <Model>Form with the fields of types a form can edit (strings, numbers, bools, time.Time as admin.DateTime, anetos.Date, and pointers to them), leaving out the key, the timestamps, JSON and read-only columns and names like password, token or secret; adds the function to Resources in app/admin/admin.go

Names may be BlogPost, blog_post or blog-post; files use snake case.

anetos add <module>[@version] and anetos remove <module>

Install and uninstall plugins, from the project’s directory or below. Both rewrite plugins.go (generated: DO NOT EDIT), which setup passes to ext.Load.

anetos add [--yes] <module>[@version] (version default latest; for Anetos’s own plugins, anetos.dev/anetos/plugins/…, the tool’s version):

  1. Prints the module and the version, and that a plugin is code that runs with the app’s privileges; runs go get <module>@<version>.
  2. Adds the package’s Plugin() to plugins.go, after the others, and runs go mod tidy (the module becomes a direct requirement).
  3. Runs go build, so a module without a Plugin() ext.Plugin function, or one that doesn’t compile against this version of Anetos, is refused.
  4. In a terminal, asks before going on (--yes, or a stdin that isn’t a terminal, doesn’t ask): the next step runs the plugin’s code on your machine, with your environment and .env. Then runs the built app’s plugin:env (stopped after 2 minutes), which loads the plugins without booting the app: if ext.Load refuses the plugin (its Requires(), its name, its settings’ names), so does anetos add. Otherwise it appends the settings .env.example doesn’t have yet (commented and export keys count as present) under a # <name> plugin line; if the app fails for another reason, it prints the error and keeps the plugin.
  5. Prints the next steps: plugin:list, and migrate if it adds migrations. Migrations never run by themselves.

If step 1 to 4 refuses the plugin, go.mod, go.sum and plugins.go are put back as they were (exit 1). When go get upgrades Anetos itself (the plugin requires a newer version), anetos add says so. Adding a module that plugins.go already lists is an error (exit 1). Import names in plugins.go avoid the names package main declares.

anetos remove takes the module out of plugins.go, runs go mod tidy and go build (putting the three files back if one fails, for example because your code still imports the plugin). The plugin’s settings stay in .env and .env.example, and its tables in the database: drop them with a migration of your own if you want them gone (migrate:rollback rolls back a whole batch, your app’s migrations included). Anetos stays at the version anetos add left it at.

anetos locale:add [--from dir] [--version v] [--force] <locale>...

Copies the translations of the framework’s messages for each locale from the module anetos.dev/locales (anetos-dev/locales) into the project’s locales/<locale>/, from the project’s directory or below (lang:add before v0.5).

  1. Downloads the module (go mod download, version --version, default latest), or uses the checkout --from names. The project’s go.mod doesn’t change.
  2. Writes framework.yaml (validation messages, error pages, login messages, format and relative), and auth.yaml when the project has locales/en/auth.yaml (make:auth’s pages and emails), without the keys the project’s other catalogs for the locale define (it lists them). A file the project already has is kept, unless --force; an identical one is reported as up to date.
  3. Prints the next step: go run . locale:check.

Locale names match the module’s folders regardless of case, and a regional locale matches its language’s folder (bn-BD writes locales/bn/). With no locale, it lists those available. It fails (exit 1), before downloading or writing anything, without a locales folder or for a locale the module doesn’t have. The download runs with GOWORK=off; without network, pass --from.

anetos doctor [--strict] [--vuln]

Checks the project, then builds the app and runs its doctor command. Run it in the project. The project’s checks:

CheckFinds
.enva warning when the file is readable by other users of the machine (chmod 600 .env; Unix)
agentswith agent files: a warning when they differ from this tool’s (an older Anetos’s, or edited between AGENTS.md’s markers): anetos agent:update
gita problem for each tracked file of settings with secrets (.env, .env.*, *.env, not *.example, *.sample, *.dist, nor the .env.testing that anetos new writes to be committed); a warning when an untracked .env isn’t ignored. Skipped outside a git repository

--vuln also runs govulncheck ./... (built in, from golang.org/x/vuln; it needs the network for vuln.go.dev); its findings fail the command. --strict makes warnings fail it too, and is passed to the app’s doctor. Exit 1 when a check finds a problem, the app doesn’t build, or the app’s doctor fails. A project that doesn’t use Anetos gets the project’s checks only, with a note. The app’s checks use the settings of this machine (.env and the environment): run ./<app> doctor with the production settings too, on the server.

anetos security:check [flags] [--no-vuln] [--url=URL [--live-only] [--allow-host=HOST]]

Checks the project’s code and dependencies, then builds the app and runs its security:check command in the project, with the same flags and what the tool found (--findings), and exits with its status: one report of the code, the dependencies, the routes and the settings. The tool’s part:

LayerChecks
CodeThe project’s packages (not their tests), type-checked, one function at a time: request data (c.Param, c.Query, c.Header, http.Request’s form, URL, headers and body, a typed handler’s input) reaching SQL (source.sql), unescaped HTML (source.xss, at the .templ line for views), a redirect (source.redirect), a command (source.exec); InsecureSkipVerify (source.tls); math/rand for secrets (source.rand); advanced: file paths (source.path) and URLs requested (source.ssrf) from the request, web.H with a model as input (source.mass-assign), records loaded by an ID from the request without an access check (source.owner), SQL built from non-constant strings (source.sql, warning)
FilesSecrets written in the project’s files (source.secret): keys recognized by their form (problem), random-looking values given to secret names (warning); not .env and other files of settings, tests, generated code, node_modules, vendor
Site (with --url)At most 24 requests (GET, a TLS handshake offering only TLS 1.0 and 1.1, a TRACE at the advanced level) to the running site, logged out, within a minute; same-host redirects followed, another host’s refused; a URL with credentials refused: security headers (live.headers), cookie flags (live.cookie), TLS (live.tls), plain HTTP and the redirect to HTTPS (live.https), /.env, /.git/, /debug/pprof/, /debug/vars served (live.exposed), stack traces in error pages (live.debug); advanced: CORS echoing a foreign origin (live.cors), TRACE (live.trace), version headers (live.version), a certificate expiring within 30 days (live.cert-expiry). The host must be APP_URL’s (the environment’s, else .env’s) or localhost, or one given with --allow-host (repeatable, or comma-separated); another is a usage error (exit 2). --live-only, or running outside a project, checks the site alone: no .env, no build; the tool writes the report itself, with the same flags, ignore file (the project’s, from a folder of it too) and exit status. In a project, a site that doesn’t answer is a warning (live.unchecked) and the rest of the report stands; with --live-only, an error
Dependenciesgovulncheck ./..., built in (dependency.vuln): a vulnerable function the app calls (problem, at the app’s line nearest the call), a vulnerable package it imports without calling it (note, at its go.mod line); without the network or after 5 minutes, a note; another failure, a warning. --no-vuln skips it (--no-vuln=false doesn’t)

A finding of the code names its function with its package’s path in the module (app/handlers.Posts.Search), as where in the ignore file. A project that doesn’t build is an error (exit 1); so is --findings, which is the tool’s. --out and --ignore name files relative to the current folder. The settings are this machine’s, as doctor’s: without a .env (and no APP_KEY in the environment) it exits 1 saying how to write one; run ./<app> security:check with the production settings too. See Check your app’s security.

anetos check [--short] [--json]

Checks that the project works, for you or a coding agent before calling a change done. In order, stopping at the first failure:

StepRuns
generatetempl’s views (go tool templ generate, when the project has .templ files), the models’ typed columns (anetos generate), and in a project with Tailwind CSS its stylesheet (downloading the tailwindcss binary on first use, as css:build does; offline, a note)
buildgo build ./...
vetgo vet ./...
testgo test ./... (--short: go test -short ./...)
doctoranetos doctor: the project’s checks and the app’s; without a .env (a fresh clone, an agent’s sandbox, CI) the project’s only, with a note saying how to write one (cp .env.example .env && go tool anetos key:generate)
securityanetos security:check --no-vuln at the basic level: a problem fails the step, its warnings are listed; without a .env, the code’s rules only (source.*), with the same note

It writes generated code, as anetos dev does, and nothing else. It prints one line per step, a failed step’s output, and doctor’s and the security check’s warnings; --json prints one object, {"ok": …, "steps": [{"step", "ok", "seconds", "output"}…]} (each step’s output, its last 16 KB), with an error when check can’t start (outside a project). Exit 1 when a step fails.

anetos docs [<page>] [--search <words>]

Prints Anetos’s documentation as Markdown, at the version of Anetos the project uses: the pages (docs/site) are built into the tool, which the project’s go.mod pins.

FormPrints
anetos docsEvery page: its name and title, by section
anetos docs <page>One page. <page> is its path without .md (guides/queues), the end of it (queues) or a word of its title; when several match, it lists them and exits 2
anetos docs --search <words> [-n 5]The pages that best match the words, each with its lines that match: whole words, plurals aside (ai isn’t in email); rare words count most, the title more than the text, and the words in a row (log in) more than apart. -n is 1 or more

A page’s relative links name pages this command prints: anetos docs ../guides/mail.md is anetos docs guides/mail, and upgrade/README.md is upgrade.

anetos agent:install and agent:update

agent:install [--agent=claude,codex,copilot,cursor,gemini] writes the files coding agents read, for the agents listed (all by default), as anetos new does unless --no-agent. See Build with a coding agent.

FileForHolds
AGENTS.mdevery agentThe project (stack, database, CSS framework), the commands, where things go, the conventions, the skills, and “run go tool anetos check”
CLAUDE.mdclaude@AGENTS.md: Claude Code imports it
GEMINI.mdgemini@AGENTS.md: Gemini CLI imports it
.claude/skills/anetos-*/SKILL.mdclaudeThe skills: anetos-crud, -auth, -migration, -job, -page (web) or -api (API), -test, -deploy, -security, -upgrade, -plugin
.agents/skills/anetos-*/SKILL.mdcodex, copilot, cursor, geminiThe same skills
.mcp.jsonclaude, copilotThe MCP server anetos (go tool anetos mcp) in mcpServers: Claude Code’s project servers, and Copilot CLI’s
.vscode/mcp.jsoncopilotThe same in servers, with "type": "stdio" and "cwd": "${workspaceFolder}": VS Code’s
.cursor/mcp.jsoncursorThe same in mcpServers, as go -C ${workspaceFolder} tool anetos mcp
.gemini/settings.jsongeminiThe same in mcpServers, with a 15-minute timeout (check runs the tests)
.codex/config.tomlcodexThe table [mcp_servers.anetos], with startup_timeout_sec = 120 and tool_timeout_sec = 900 (Codex reads a project’s file once you trust the project)

The MCP files are shared with your own servers and settings: the anetos entry is added when the file has none, and the rest kept. An entry named anetos is left as it is, the tool’s (which you may have edited, adding an env or --dir) or your own. A JSON file is rewritten with its keys sorted (JSON doesn’t keep their order), its numbers as written; one with comments is refused, with the entry to add yourself, and the other files are still written (exit 1). The files are those of exactly the agents listed: Anetos’s skills in a folder none of them reads are removed (--agent=claude removes .agents/skills/anetos-*), and so is the tool’s anetos entry from the others’ MCP files (with its subtables in TOML; a file left empty goes); CLAUDE.md and GEMINI.md stay, being partly yours. It keeps what you wrote: in AGENTS.md, the text outside the markers <!-- anetos:begin … --> and <!-- anetos:end --> (a file without them gets Anetos’s text first, then its own); in CLAUDE.md and GEMINI.md, everything, with the import added first when missing; skills not named anetos-*. Running it again changes only what differs.

agent:update rewrites them for this version of Anetos, for the agents whose files the project has (.claude/skills/anetos-* for claude; with .agents/skills/anetos-*, codex, copilot and cursor by their MCP files’ anetos entry, or codex without any; gemini by GEMINI.md’s import and .gemini/settings.json’s entry), and removes nothing: run it after an upgrade (doctor warns when they differ, line endings aside). It fails in a project without agent files. The project’s name in the files is its binary’s (deploy/<name>.service, else the module’s last part), not its folder’s, so a clone or worktree under another name doesn’t change them.

anetos mcp [--dir=<project>]

An MCP server on the standard input and output, which coding agents start from the files agent:install writes (go tool anetos mcp, so it’s the project’s version of Anetos). Its tools read the project and the documentation, and check changes. None changes your code or data: check writes generated code, as anetos dev does, and the app’s commands create what the app creates when it starts (storage/, an empty SQLite database):

ToolDoes
docs_list, docs_read, docs_searchanetos docs: the pages, one page, a search
model_listmodel:list --json
app_about, route_list, db_schema, migrate_status, command_listThe app’s about, route:list, db:schema, migrate:status and help, with --json: it builds the app (go build, cached) and runs the command in the project, which needs a .env
checkcheck --json; an error result when a step fails
doctordoctor’s report; an error result on a problem
security_checksecurity:check --format=json (level: basic or advanced; url: the running site too; vuln: govulncheck too, off by default); an error result on a problem, a usage error’s message when it can’t run

The project is --dir’s, else the one around the directory the agent starts it in. go tool itself needs to start in the project (outside it, go tool anetos isn’t found): an agent that starts its servers elsewhere runs go -C <project> tool anetos mcp, as Cursor’s entry does. One check runs at a time; the app is built into a temporary folder, removed when the server stops. Its instructions tell the agent to search the docs before guessing an API and to run check before calling a change done. gopls has an MCP server of its own for Go itself (gopls mcp): add it to the same files if you have gopls.

Other commands

CommandDoes
anetos generate [--check] [packages]Typed model columns (reference)
anetos model:list [--json] [packages]The models, read from the code as generate reads it, so the app needn’t run: each one’s package, file and table (its TableName method’s string, else the plural of its name in snake case), its columns (the column, the typed column’s field in <Model>Cols, the Go type, json) and its relations (the field, belongs_to, has_one, has_many or many_to_many, the related model). --json prints a list of {"package", "name", "table", "table_method", "file", "columns", "relations"}. Packages default to ./...
anetos css:build [--check]In a project that uses Tailwind CSS: compiles views/ui/tailwind.css into public/static/app.css with Tailwind CSS’s standalone CLI (--input views/ui/tailwind.css --minify), writing it only when it changes. The first run downloads Tailwind CSS 4.3.3 for the platform from its GitHub releases into the user cache directory (<cache>/anetos/tailwindcss/v4.3.3/), checking the SHA-256 written in anetos then and before each run (a download that sends nothing for 30 s stops); ANETOS_TAILWIND=<path> runs that binary instead (its version is checked, and a different one warned about). --check writes nothing and exits 1 when app.css is out of date. Exits 1 in a project without views/ui/tailwind.css (Tailwind CSS)
anetos css:use [<framework>] [--force]Switches a web project’s CSS framework: writes its files in views/ui and public/static/, removes the old one’s files the new one lacks (and their _templ.go), records the framework in views/ui/css.json (its name and version, the SHA-256 of each file), adds nav.menu to locales/en/app.yaml if missing (or says what to add, when it can’t edit the file safely; and names the other locales without it), runs templ generate, and for tailwind css:build (going on without Tailwind: the app.css anetos ships is compiled for the components). Exits 1, writing nothing, when a recorded file changed since (line endings aside) or is a symbolic link, when a file in the new framework’s way isn’t the old one’s (it lists them), or when the project has no usable css.json (missing, not JSON, or naming a file outside views/ui and public/static): --force replaces them (without a record, it lists public/static’s files that aren’t the new framework’s instead of removing them). Each file is written through a temporary file, the record last. Then runs go build ./..., exiting 1 when the project doesn’t build with the new framework. With the project’s own, updates its files to this version’s. Lists your own files in views/ui, which keep their classes, and the Dockerfile cache line to add or remove when moving to or from Tailwind. Without <framework>, prints the project’s. Refused in a project without views/ui (an API project, or one made before v0.5) (Style your app)
anetos key:generate [--show] [--force]Sets APP_KEY in .env to a new key when it is missing or empty (it used to print it); refuses when it is set, unless --force, which moves the old key to the front of APP_PREVIOUS_KEYS. --show prints APP_KEY=base64:… on stdout instead, for a server’s environment; the other messages go to stderr
anetos versionPrints the tool’s version

A command’s name may be shortened, each part between colons, while it stays unique, among the commands with as many parts: anetos g is generate, anetos k:g key:generate, anetos m:admin make:admin (the part written whole wins over make:admin-resource); an ambiguous one (anetos d: dev, docs or doctor) lists the candidates and exits with status 2. Before v0.5, locale:add was lang:add (or add lang) and make:admin-resource was make:admin:resource: the old names still run, with a warning, until v0.6. generate was gen, which is one of its short forms.

App binary commands

app.Execute() runs the command named by the first argument, which may be shortened, each part between colons, while it stays unique among the commands with as many parts: ./app r:l is route:list, ./app mi migrate. (version is handled before the app is set up only when written whole.) Before v0.5, route:list was routes:list, plugin:list and plugin:env were plugins:list and plugins:env, and locale:check was lang:check: the old names still run, with a warning, until v0.6 (cmd.Command.Former).

CommandAdded byDoes
(none), run [--only=type,…]every appRuns the background components (all, or those of the process types web, worker, scheduler, listener, plus those without one) until SIGINT/SIGTERM (exit 0)
serveweb.NewServerrun --only=web
route:list [--json]web.NewServerMethod, path and name of every route. --json: {"middleware": […], "routes": [{"method", "host", "path", "name", "handler", "input", "output", "status", "file", "line", "public", "middleware": […]}]}, the global middleware first; file and line are where the route was registered (relative to the module’s folder), public the reason given to Public (both omitted when empty); each middleware is {"name", "detail", "security", "scopes", "responses"}, named as Go code names it (web.CSRF, session.Manager.Middleware, auth.Auth.Require, rbac.Require with its permissions as detail, ratelimit.Middleware with its limit’s name), what it said with web.Documented (web.MiddlewareDoc), outermost first. security is what an API description shows: auth.Auth.Require says bearer on pages too, where the user comes from the session. Login attempts are limited inside auth’s login (AUTH_THROTTLE), not by a middleware, so POST /login lists none
openapi [--check] [--out=FILE]openapi.RegisterWrites the API’s OpenAPI 3.1 description to openapi.json (Config.File; --out=-: the standard output), warning about routes it leaves out; --check exits 1 if the file differs. Doesn’t boot the app. See Describe an API with OpenAPI
health:check [--live] [--timeout=5s]web.NewServerAsks the server running on HTTP_ADDR (on 127.0.0.1 when its host is empty, 0.0.0.0 or [::]) for /health/ready (--live: /health/live), for container health checks: prints ok, or exits 1. An error with HTTP_HEALTH_ROUTES=false
migrate, migrate:rollback, migrate:reset, migrate:fresh, migrate:status [--json], db:seed, db:schema [--json] [table…]migrate.NewSee the migrations reference; db:schema describes the tables: columns, indexes, foreign keys
search:reindex [table…]migrate.NewRebuilds the search indexes (all, or the tables’) for DB_SEARCH_LANGUAGE and DB_SEARCH_RANKING. See Search
ai:embed [table…]ai.EmbeddingsForEmbeds the records whose text or embedding model changed (all tables’, or the named ones), a hundred at a time; unchanged chunks aren’t embedded again. See Search by meaning
cache:clearcache.NewRemoves the app’s cache items (keys with CACHE_PREFIX), locks included
queue:workqueue.NewRuns only the workers, as run --only=worker; the queues and concurrency are those the app’s Work call sets
queue:failed [--limit=N], queue:retry <id>…|all, queue:forget <id>…, queue:flush [--force], queue:clear [--force] [queue]queue.NewList, retry and delete failed jobs; delete the jobs waiting on a queue. flush and clear need --force in production. See Queues
pubsub:publish <topic> <message>pubsub.NewPublishes a message (its body as given) to a topic. See Pub/sub listeners
locale:check [dir]i18n.NewReports keys a supported locale lacks (against APP_FALLBACK_LOCALE’s), placeholders that differ, plural forms a language needs, and keys the .go and .templ files under dir (default .) use that no catalog has (a literal followed by + is a prefix some key must start with); notes the framework’s messages a locale leaves in English. Exits 1 on a problem; doesn’t boot the app. See Translations
schedule:list [--json]schedule.NewEach task, its schedule, its next run and options (--json: name, schedule, next, without_overlapping, on_one_server, timeout). See Scheduling
schedule:runschedule.NewRuns the tasks due this minute, once, with their locks, and exits: for cron or a Kubernetes CronJob every minute (with a task’s name it runs that task, as schedule:test, with a warning, until v0.6)
schedule:test <task>schedule.NewRuns a task now, whatever its schedule (WithoutOverlapping applies, across processes only with a shared cache store; OnOneServer doesn’t)
schedule:workschedule.NewRuns only the scheduler, as run --only=scheduler
rbac:roles, rbac:user <user-id>, rbac:assign [--scope=kind:id] <user-id> <role>, rbac:unassign …rbac.NewList the roles and their users; show a user’s grants; give or take a role. See Roles and permissions
db:prune-trashed [--dry-run]db.PrunableDeletes for good the rows of the registered models soft-deleted longer ago than their duration; --dry-run counts them. See Keep an audit log
audit:pruneaudit.NewDeletes the audit entries older than AUDIT_RETENTION_DAYS, and records that it did
audit:anonymize <actor-type> <actor-id>audit.NewReplaces an actor (user 42) with erased in the audit log, as the actor and as the user someone impersonated, and drops the IP addresses of their entries, for erasure requests. See Keep an audit log
plugin:list [--json]ext.LoadEach plugin, its version constraint, its route prefix and what it adds (or that its settings are missing); --json adds its settings (name, default, required); doesn’t boot the app. See Use plugins
plugin:env [plugin]ext.LoadThe plugins’ settings as .env lines with their defaults (double-quoted when they need it; # required after required ones); doesn’t boot the app, so it works before they are set
about [--json]every appDescribes the app: its name, environment, URL, time zone, module, the Anetos and Go versions, process types, the services provided (*db.DB, *queue.Queue…), its components, and the settings it read while booting with their values (<value> (default) for a default; (not set) without one, listed only by --json). A secret is (set) (a name with KEY, SECRET, PASSWORD, PASS, TOKEN, CREDENTIAL, PRIVATE, DSN or WEBHOOK), and in the other values a connection string’s password and a URL’s secret parameters and user are xxxxx (a URL that doesn’t parse is xxxxx whole); a value read under its former name is <value> (from <former>). It can’t know every secret a value may hold: read it before you share it. It boots the app, as other commands do
doctor [--strict]every appRuns the app’s checks of its settings and prints what they find (see below). Exit 1 on a problem (--strict: on a warning too)
security:check [--level=basic|advanced] [--format=text|json|sarif|markdown] [--out=FILE] [--ignore=FILE] [--strict] [--findings=FILE]every appChecks the app’s settings and routes against security rules and reports what they find, with the anetos tool’s findings about the code (see below). Exit 1 on a problem (--strict: on a warning too)
versionevery appThe app’s version (--version of anetos build, else the git tag Go recorded), commit, commit time and modified if the files differed from it; the Anetos version; the Go version and system. Doesn’t boot the app; the main.go of anetos new prints it before setup, so it needs no settings (anetos.VersionText)
help [--json] [command], -h, --helpevery appThe command list (--json: each command’s name, usage and description), or a command’s usage (<command> -h too, as the first argument); doesn’t boot the app
APIDoes
app.Command(name, description, run)Adds a command; panics if the name is invalid (lowercase words joined by : or -) or taken
app.AddCommand(cmd.Command{Name, Usage, Description, Run, ManagesApp, ChangesSchema, Former})The same, returning an error. Former: the command’s former names, still run (with a warning) but not listed. ChangesSchema: the command changes the database’s structure, so boot checks that the schema matches the settings (search indexes) don’t stop it
cmd.Running(ctx)The command the app is booting or running for, in boot code (cmd.WithCommand sets it)
app.Commands()Every command, sorted
app.Execute()Runs os.Args[1:] with a context canceled by SIGINT/SIGTERM, then exits
app.ExecuteArgs(ctx, args, stdout, stderr)Runs and returns the exit status (tests)
args.Parse(fs)Parses args.Args with a flag.FlagSet; bad flags give an error matching cmd.ErrUsage (exit 2)
cmd.Usagef(format, …)A usage error (exit 2)

The doctor command

doctor runs every check added with app.AddCheck, the ones features add as they are set up included, and prints one line per finding (ok for a check with none), then the counts. Checks that don’t need services run first, without booting the app; then it boots the app (connecting to the database…), reporting a failed boot as a problem, and runs the others, with those added while it booted. An app that was booted already (in a test) stays open. Checks of deployment settings apply with APP_ENV production or staging only.

Checking blog (APP_ENV=production).
  ok       app
  ok       db
  warning  mail: MAIL_DRIVER=log in production: emails aren't sent; set MAIL_DRIVER=smtp (with MAIL_SMTP_URL) or a plugin's driver
  ok       session
  ok       http
  note     cache: CACHE_DRIVER=memory: each instance of the app has its own cache, rate limits and locks (cache.WithLock); with more than one instance, use redis or database
  ok       migrations
0 problems, 1 warning, 1 note.
CheckAdded byFinds
appevery appIn production and staging: APP_KEY not set (warning), APP_URL not set (warning), http:// for a host other than this machine (problem in production, warning in staging), or an example’s domain (example.com, .test: warning), APP_DEBUG=true in staging (warning; production refuses it)
dbdb.ConnectIn production and staging: DB_LOG_QUERIES=true (warning); for PostgreSQL and MySQL, a server other than this machine reached without verifying its certificate (warning), from DB_TLS (none, skip-verify) or from DB_URL: PostgreSQL’s sslmode must be verify-full, or verify-ca or require with an sslrootcert file (the server’s own authority); MySQL’s tls must be true or a registered configuration that checks certificates, without allowFallbackToPlaintext. With several hosts, the worst one counts. A DB_URL the driver can’t read is a warning
migrationsmigrate.NewAfter booting: migrations that haven’t run (warning), applied ones the app no longer has (note); on MySQL and MariaDB, tables (not views) with text columns in a character set other than utf8mb4 or ascii (warning, with the ALTER TABLE … CONVERT TO CHARACTER SET utf8mb4 that fixes them)
sessionsession.NewSESSION_SECURE=false in production or staging (problem); SESSION_SAME_SITE=none (warning); SESSION_DOMAIN set (note)
httpweb.NewServerHTTP_TRUSTED_PROXIES with 0.0.0.0/0 or ::/0 (problem) or a range wider than /8 (IPv4) or /16 (IPv6) (warning); HTTP_CORS_ORIGINS=* (warning); in production and staging, HTTP_MAX_BODY, HTTP_REQUEST_TIMEOUT or HTTP_READ_HEADER_TIMEOUT set to 0 (warning)
mailmailer.NewMAIL_DRIVER log or memory in production or staging (warning); no MAIL_FROM_ADDRESS for a driver that sends (warning); tls=none in MAIL_SMTP_URL for a server other than this machine (warning); in production and staging, an example’s domain (example.com, .test) as MAIL_SMTP_URL’s server or MAIL_FROM_ADDRESS’s (warning)
cachecache.NewCACHE_DRIVER=memory in production or staging (note)
queuequeue.NewIn production and staging: QUEUE_DRIVER=memory (warning), sync (note)
APIDoes
app.AddCheck(anetos.Check{Name, Booted, Security, Run})Adds a check: Run(ctx) []anetos.Finding, nothing when all is well; Booted runs it after the app boots (for checks that need a service); Security puts all its findings in security:check’s report too. Checks run in the order added, the booted ones last; a panic is reported as a problem. Panics without a name or Run
anetos.Finding{Severity, Message, Rule}What a check found; the message names the setting and says what to do. Rule, for a finding about security, is its rule in security:check’s report (setting.session-secure)
anetos.Note, anetos.Warning, anetos.ProblemThe severities: information; often a mistake; unsafe or broken (exit 1)
env.Deployed()Whether an anetos.Environment is production or staging
db.Driver.InspectURLFor drivers: reads a DB_URL’s host and TLS mode (db.TLSVerify, TLSSkipVerify, TLSNone), for the db check

The security check

security:check boots the app, runs the doctor’s checks and keeps their findings about security (a finding with a Rule, or every finding of a check marked Security, as check.<name>), then runs the security rules the features and the app added, at the level asked for. It reads security-ignore.yaml at the project’s root (--ignore names another file), and sorts the findings by severity. The rules and the ignore file: Check your app’s security.

FlagDefaultMeaning
--levelbasicbasic: the rules with few false alarms; advanced adds those that find what may be on purpose
--formattexttext; json, one object (app, env, level, findings and ignored, each with rule, severity, where, file, line, message, owasp, and docs or reason; summary; limits); sarif, SARIF 2.1.0 for GitHub’s code scanning (a route’s finding at the line that registered it, a setting’s at its line in .env.example, else go.mod’s first); markdown, a table
--outthe standard outputWrites the report to a file and prints the counts; - is the standard output
--ignoresecurity-ignore.yamlThe file of ignored findings: a list of rule, where (every place when empty), reason (required), expires (2027-03-31, through the end of that day in APP_TIMEZONE); another key is an error. A file named here must exist
--strictoffExit 1 on a warning too
--findingsnoneA file of findings to add, as JSON: {"rules": [{"id", "summary", "owasp", "docs"}], "findings": [{"rule", "severity", "where", "file", "line", "message"}]}; the anetos tool writes it with its findings about the code

A finding is ignored by the first entry that matches it and hasn’t expired. An expired entry whose finding is reported is a warning (ignore.expired), and an entry that ignores nothing a note (ignore.unused). A check or rule that panics is a problem (check.panic). In SARIF, files are relative to the git repository’s root (%SRCROOT%), each rule has a security-severity (the worst of its findings: 8.0, 5.0, 2.0), and each result a fingerprint of its rule, place and file.

APIDoes
app.AddSecurityRule(anetos.SecurityRule{ID, Level, Summary, OWASP, Docs, Run})Adds a rule: Run(ctx, app) []anetos.SecurityFinding, called after the app boots. Level: anetos.SecurityBasic (default) or anetos.SecurityAdvanced. Panics without a dotted lower-case ID (billing.webhook-signature; route., setting., check. and ignore. are the framework’s) or Run, or with an ID already added
anetos.SecurityFinding{Rule, Severity, Where, File, Line, Message, OWASP}What a rule found: Where names the place (a route, a setting); File and Line the code; Rule and OWASP default to the rule’s. Its JSON is the report’s (anetos.Severity marshals as its name)
web.RouteRule(rule, func(web.RouteInfo) []anetos.SecurityFinding)A rule that checks each route of the app’s server, its global middleware first; a finding’s Where defaults to the route (POST /posts), its File and Line to where it was registered: the app’s line that registered it, or that called the module that did (the admin’s Mount)
RouteInfo.Uses(name), RouteInfo.String()Whether a route has a middleware (MiddlewareDoc.Name); the route as reports name it
route.Public(reason)Marks a route open to everyone on purpose: route.login and route.api-auth leave it out, and route:list --json shows the reason (public). Panics on an empty reason
anetos.OWASPAccessControl, OWASPMisconfiguration, OWASPCryptographic, OWASPAuthentication, OWASPLoggingOWASP Top 10:2025 categories, for OWASP

A command other than run and serve runs after app.Boot, with a context from app.Context; app.Close follows, also after a panic. The context is canceled by the first SIGINT/SIGTERM (the command fails with exit 1 if it stops early); the second ends the program. An app runs one command.