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
| Command | Use |
|---|---|
go install anetos.dev/anetos/cli/cmd/anetos@latest | For anetos new, before you have a project |
go get -tool anetos.dev/anetos/cli/cmd/anetos@latest | In 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>
| Flag | Default | Meaning |
|---|---|---|
--module | the directory’s name | Go module path |
--db | sqlite | sqlite, postgres or mysql: the driver in main.go and the DB_* settings in .env |
--stack | web | web: pages rendered on the server, with sessions and CSRF protection; api: JSON only, no views or static files, sessions only for its own SPA’s login (the API project); with --vite, a single-page app served at /; react, vue and svelte (since v0.6): the web stack’s routes, handlers and sessions, with pages that are React, Vue or Svelte components, which Inertia’s client renders, in TypeScript (the Inertia stacks) |
--css | anetos | The 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; with --stack=react, vue and svelte, only anetos |
--vite[=ts|js] | none | A frontend that Vite builds, in TypeScript (--vite) or JavaScript (--vite=js) (since v0.6): the web stack’s layout loads it; the api stack’s is a single-page app the app serves at / (and anetos new runs go run . types, its client). See vite:install, which writes the same; anetos new then installs its packages with npm (Node.js 20.19 or 22.12 or later; without Node.js, it says so and goes on). Refused with --stack=react, vue and svelte, which have a frontend |
--no-agent | false | Don’t write the files coding agents read (AGENTS.md, CLAUDE.md, GEMINI.md, the skills); see agent:install |
--skip-install | false | Only write the files |
--replace | A 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; the react, vue and svelte stacks run go run . types
last, writing the frontend’s types, then installs its packages with
npm, as --vite does). With --db=postgres or
mysql, create the database before migrate.
The web stack’s files:
| Path | Holds |
|---|---|
main.go | anetos.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.go | The plugins, written by anetos add and anetos remove (an empty list at first) |
main_test.go | Tests requesting the home page and a missing page with anetostest |
.env, .env.example | Settings; .env has a fresh APP_KEY (file mode 0600) and stays out of git |
.env.testing | PostgreSQL and MySQL projects: the test database’s settings (<name>_test) |
README.md, .gitignore | How to run it; what stays out of git |
routes/web.go | Routes: 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.go | The home page handler |
app/models/ | Models (empty at first) |
database/migrations/migrations.go | The All migration set and Seeders |
database/factories/factories.go | The package for model factories (empty at first) |
views/layout.templ, views/home.templ | templ 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.yaml | The 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.svg | public.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, .dockerignore | A 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.example | A 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.md | The 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:
| Path | Holds |
|---|---|
routes/api.go | Register(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.go | GET /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.yaml | The API’s English messages |
main_test.go | Tests of GET /api/v1, of a missing URL’s problem details, and that openapi.json is up to date (openapi.Check) |
openapi.json | The 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 |
frontend/, public/public.go | With --vite (since v0.6): the single-page app and its build’s folder, served at / (Build a single-page app; see vite:install) |
.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.
The Inertia stacks
--stack=react, --stack=vue and --stack=svelte (since v0.6) write
the web stack’s files but its views, views/ui and public/static/:
the routes, handlers and sessions are the same, and the pages are React,
Vue or Svelte components that Inertia’s client renders with the props the handlers
send (Pages in Vue, React or Svelte with
Inertia). In place of the
web stack’s views, the react stack writes:
| Path | Holds |
|---|---|
main.go | The web stack’s, with vite.New(app, public.Files, vite.WithReactRefresh()), inertia.New(app, views.App(), inertia.WithShared(handlers.SharedProps), inertia.WithPages(handlers.Pages...)) and typescript.Register(app, srv, typescript.Config{Inertia: in, Routes: true, ExcludeRoutes: []string{"admin."}}) (the admin’s routes stay out of routes.ts) |
app/handlers/pages.go | Pages and page[P](component), which declares a page and adds it to them; Shared, the props of every page: appName, locale, dir, timeZone (the user’s, for useFormat()’s times), routePrefix, notice (the status flash; not status, which the error page’s props have: a page’s prop replaces a shared prop of its name), user (currentUser: nil until make:auth) and messages (the locale’s translations, i18n.Messages, a once prop) |
app/handlers/home.go | The home page’s handler: homePage.Render(c, HomeProps{}) |
routes/web.go | The web stack’s, with inertia.ErrorPages("Error"), the build’s files under /build/, and web.CSRF(web.WithXSRFCookie()) and inertia.Middleware on the page group |
views/app.templ | The root view: the first visit’s HTML, with @vite.Tags("src/app.tsx") and @inertia.App() |
public/public.go, public/robots.txt, public/favicon.svg | public.Files, the web root, with the frontend’s build in public/build |
frontend/package.json, vite.config.ts, tsconfig.json, go.mod | The frontend: @inertiajs/react, React, Vite and TypeScript; the build into ../public/build, with its manifest |
frontend/src/app.tsx, src/Layout.tsx | createInertiaApp, with the layout around every page: the header with its nav (NavLink, which marks the current page), the flashed status and the footer |
frontend/src/pages/Home.tsx, src/pages/Error.tsx | The home page, and the error pages’ component |
frontend/src/components/ui.tsx, src/theme.css, src/app.css | The components the pages are made of (PageHeader, Card, Field, Input, Button, PostButton, Table, Pagination…), writing the starter theme’s markup; the starter theme; the app’s own styles |
frontend/src/i18n.ts | useT(), which translates with the messages prop (placeholders and plurals), and useFormat(): the locale’s numbers and dates |
frontend/src/types/ | pages.ts (the pages’ props), routes.ts (route(name, params, query) over the named routes) and api.ts (the typed handlers’ types and client), written by go run . types |
The vue stack writes the same with Vue’s files: vite.New(app, public.Files) in main.go; @inertiajs/vue3, Vue, Vite, TypeScript 6
and vue-tsc, which type-checks the .vue files in npm run build
(TypeScript 7, which the react stack has, lacks the JavaScript API
vue-tsc uses); the entry src/app.ts (in views/app.templ’s
@vite.Tags); src/Layout.vue, src/components/NavLink.vue; the
components in src/components/ui/, a .vue file each, which
src/components/ui/index.ts exports; and src/pages/Home.vue and
Error.vue. A page declares its own props with their type from
pages.ts (defineProps<TasksIndexProps>()), and reads the shared ones
with usePage().
The svelte stack writes the same with Svelte 5’s files: vite.New(app, public.Files); @inertiajs/svelte, Svelte, Vite, TypeScript 6 and
svelte-check, which type-checks the components in npm run build;
svelte.config.js; the entry src/app.ts; src/Layout.svelte,
src/components/NavLink.svelte; the components in
src/components/ui/, with Title for a page’s title (Inertia’s Svelte
client has no Head); src/routes.ts, route() with the current
page’s locale prefix, which the pages import; and src/pages/Home.svelte
and Error.svelte. A page takes its props with their type
(let { page }: TasksIndexProps = $props()).
make:auth and make:crud write the same Go as in the web stack, whose
handlers render the stack’s pages, and update the types; make:admin adds its
banner to views/app.templ (the first visit’s HTML, so it shows and
goes away with a full page load). css:use refuses other frameworks:
the stack has the starter theme. ExcludeRoutes keeps the admin’s
routes out of routes.ts, and out of the frontend’s bundle. A project is of a stack when frontend/package.json
depends on its adapter (@inertiajs/react, @inertiajs/vue3, @inertiajs/svelte) and
app/handlers/pages.go declares page: a web project with Inertia added by hand keeps the web stack’s
generators.
anetos dev
| Flag | Default | Meaning |
|---|---|---|
--addr | HTTP_ADDR from .env, else :8080; without a host, on 127.0.0.1 only | Where 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) |
--host | localhost, *.localhost, IP addresses and APP_URL’s host | Another 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… | run | Arguments for the app binary |
Run it in the project (any directory under go.mod). On start and on
every change it:
- runs
go tool templ generate(if there are.templfiles) andanetos generate, and in a project that uses Tailwind CSS compilespublic/static/app.cssascss:builddoes (when Tailwind can’t run, it says why and keeps theapp.cssthere is until it’s restarted), - builds the app into
tmp/anetos-dev/, and, in an app that callstypescript.Registerinmain.go, runs itstypescommand, which writes the frontend’s TypeScript types that changed (a failure is logged; since v0.6), - stops the previous app (interrupt, then kill after 10 s) and starts the
new one with
HTTP_ADDRset to a free local port, - once the app accepts connections, tells open pages to reload.
In a web project with a frontend (frontend/package.json; since v0.6),
it first installs the frontend’s packages if node_modules is missing
or older than package.json or the lockfile (with the lockfile’s
package manager, npm, pnpm, yarn or bun, updating the lockfile after an
edit of package.json), then runs Vite
(node frontend/node_modules/vite/bin/vite.js --host 127.0.0.1 --port <free port> --strictPort --clearScreen false; the flags win over
vite.config). Requests under /build/ go to Vite, WebSocket upgrades
included, with Vite’s own host name; the app gets VITE_DEV_URL=/build/.
Vite updates the page as the frontend’s files change; the app isn’t
rebuilt for them.
In an API project whose main.go calls vite.SPA (its single-page app,
which vite:install adds; since v0.6), it runs Vite at the address of
its vite.config instead (node frontend/node_modules/vite/bin/vite.js --clearScreen false: http://localhost:5173, which forwards /api to
the app), and forwards nothing to it: open Vite’s address. Another API
project’s frontend/ is an app of its own, which anetos dev, build
and check leave alone.
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] [--no-frontend] [-- go build flags]
| Flag | Default | Meaning |
|---|---|---|
-o | bin/<name>: the module path’s last element, or the one before a /v2 suffix (.exe for Windows) | The binary to write |
--target | go env GOOS/GOARCH | The system to build for: linux/amd64, linux/arm64, windows/amd64… The generators still run on this one |
--version | the 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 repository | The app’s version, for its version command: letters, digits and . + - _ ~ / |
--cgo | false | Build with CGO_ENABLED=1 (only for a driver or package that needs cgo; SQLite doesn’t) |
--no-frontend | false | Don’t build frontend/: public/build (an SPA’s public/spa) holds its build already (the Dockerfile’s Node stage made it). Since v0.6 |
-- 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), in a project with
a frontend (a web project’s, or an API project’s SPA) its packages’ install if they need it (as the lockfile pins
them: npm ci) and its build script
(TypeScript’s checks and vite build into public/build, or an API
project’s SPA into public/spa; Node.js
needed, unless --no-frontend), 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).
| Command | Writes |
|---|---|
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 it writes nothing and names css:use --force, which writes one. Writes nothing if a file or the migration exists or a name is taken. See Add pages for a model. In a project of an Inertia stack (since v0.6): the same Go, whose handlers render the pages frontend/src/pages/<Models>/Index, Show and Form (.tsx, .vue or .svelte) (<Models>/Index gets page, a db.Page of <Model>Item; Show and Form get item), in place of the views; the link in the layout’s nav (frontend/src/Layout.tsx, .vue or .svelte), after its last NavLink; then go run . types. 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:auth | Accounts, 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, it writes nothing, as make:crud. 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 a project of an Inertia stack (since v0.6): the same Go and emails, whose handlers render the pages of frontend/src/pages/Auth/ (Register, Login, ForgotPassword, ResetPassword, TwoFactorChallenge, ConfirmPassword, TwoFactor, Dashboard, Settings, RevertEmail), with frontend/src/components/AccountMenu and SocialButtons, in place of views/auth.templ; currentUser in app/handlers/pages.go returns authUser(c), so every page gets the logged-in user, and <AccountMenu /> takes the place of the comment left for it in the layout (frontend/src/Layout.tsx, .vue or .svelte) (else it prints what to change); then go run . types. 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, sessions), with TokenMiddleware, and, for the SPA of HTTP_SPA_ORIGINS (since v0.6), sessions and CSRF through web.FirstParty; the account’s routes need a token with every ability, auth.RequireAbilities("*")), auth.go (setupAuth(app, r), with session.New since v0.6; 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:admin | The 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 (in the Inertia stack, the root view, views/app.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):
- Prints the module and the version, and that a plugin is code that
runs with the app’s privileges; runs
go get <module>@<version>. - Adds the package’s
Plugin()toplugins.go, after the others, and runsgo mod tidy(the module becomes a direct requirement). - Runs
go build, so a module without aPlugin() ext.Pluginfunction, or one that doesn’t compile against this version of Anetos, is refused. - 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’splugin:env(stopped after 2 minutes), which loads the plugins without booting the app: ifext.Loadrefuses the plugin (itsRequires(), its name, its settings’ names), so doesanetos add. Otherwise it appends the settings.env.exampledoesn’t have yet (commented andexportkeys count as present) under a# <name> pluginline; if the app fails for another reason, it prints the error and keeps the plugin. - Prints the next steps:
plugin:list, andmigrateif 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.
- Downloads the module (
go mod download, version--version, defaultlatest), or uses the checkout--fromnames. The project’sgo.moddoesn’t change. - Writes
framework.yaml(validation messages, error pages, login messages,formatandrelative), andauth.yamlwhen the project haslocales/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. - 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:
| Check | Finds |
|---|---|
.env | a warning when the file is readable by other users of the machine (chmod 600 .env; Unix) |
agents | with 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 |
git | a 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:
| Layer | Checks |
|---|---|
| Code | The 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) |
| Files | Secrets 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 |
| Dependencies | govulncheck ./..., 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:
| Step | Runs |
|---|---|
generate | templ’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) |
frontend | In a web project with a frontend (frontend/package.json), or an API project that serves its SPA (vite.SPA; since v0.6): its packages’ install if they need it, and its build script (TypeScript’s checks, vite build into public/build or public/spa); it needs Node.js |
build | go build ./... |
vet | go vet ./... |
test | go test ./... (--short: go test -short ./...) |
doctor | anetos 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) |
security | anetos 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.
| Form | Prints |
|---|---|
anetos docs | Every 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.
| File | For | Holds |
|---|---|---|
AGENTS.md | every agent | The project (stack, database, CSS framework), the commands, where things go, the conventions, the skills, and “run go tool anetos check” |
CLAUDE.md | claude | @AGENTS.md: Claude Code imports it |
GEMINI.md | gemini | @AGENTS.md: Gemini CLI imports it |
.claude/skills/anetos-*/SKILL.md | claude | The skills: anetos-crud, -auth, -migration, -job, -page (web) or -api (API), -test, -deploy, -security, -upgrade, -plugin |
.agents/skills/anetos-*/SKILL.md | codex, copilot, cursor, gemini | The same skills |
.mcp.json | claude, copilot | The MCP server anetos (go tool anetos mcp) in mcpServers: Claude Code’s project servers, and Copilot CLI’s |
.vscode/mcp.json | copilot | The same in servers, with "type": "stdio" and "cwd": "${workspaceFolder}": VS Code’s |
.cursor/mcp.json | cursor | The same in mcpServers, as go -C ${workspaceFolder} tool anetos mcp |
.gemini/settings.json | gemini | The same in mcpServers, with a 15-minute timeout (check runs the tests) |
.codex/config.toml | codex | The 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):
| Tool | Does |
|---|---|
docs_list, docs_read, docs_search | anetos docs: the pages, one page, a search |
model_list | model:list --json |
app_about, route_list, db_schema, migrate_status, command_list | The 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 |
check | check --json; an error result when a step fails |
doctor | doctor’s report; an error result on a problem |
security_check | security: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
| Command | Does |
|---|---|
anetos generate [--check] [packages] | Typed model columns (reference); then, in an app that calls typescript.Register in main.go, go run . types [--check] (since v0.6) |
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 an API project (no views/) and, for another framework than anetos, in the Inertia stacks, which have the starter theme; in a web project without views/ui or views/ui/css.json, --force writes the framework’s files (Style your app) |
anetos vite:install [--js] [--skip-install] | Adds a frontend that Vite builds to a web project (since v0.6; guide): frontend/ (package.json, vite.config.ts, tsconfig.json, src/main.ts, src/main.css; with --js, vite.config.js and src/main.js without tsconfig.json; and a go.mod that keeps the go command out of node_modules), vite.New(app, public.Files) in main.go’s setup before web.NewServer, the /build/ route after /assets/ in routes/web.go, @vite.Tags("src/main.ts") after @ui.Head() in views/layout.templ, frontend/node_modules/ and public/build/ in .gitignore and .dockerignore, and a Node stage in the Dockerfile (its build copied into the Go stage, anetos build --no-frontend there). A file it can’t find its place in is left alone, with what to add printed (the layout too when main.go is: the tags need vite.New); CRLF files keep their line endings. Refused in a project with frontend/. Then it runs templ generate, and installs the packages with npm, unless --skip-install or Node.js is missing (said so). In an API project, a single-page app instead (guide): frontend/ with package.json, tsconfig.json, go.mod, vite.config.ts (port 5173, /api forwarded to 127.0.0.1:8080, the build into ../public/spa), index.html, src/main.ts (with make:auth’s routes, run before: a login with two-factor codes, a registration, a logout, and the /verify-email and /reset-password pages the emails link to; else the API’s welcome) and src/style.css (with --js, vite.config.js and src/main.js without tsconfig.json); public/public.go (public.Files; an existing one is kept, and must declare Files); in main.go’s setup after openapi.Register, typescript.Register (unless there) and vite.SPA(app, public.Files, vite.Except("/api/")) as srv.Router().Fallback; frontend/node_modules/ and public/spa/ in .gitignore and .dockerignore; the Node stage in the Dockerfile; HTTP_SPA_ORIGINS (when empty) listing http://localhost:5173 and APP_URL’s origin in .env and .env.example, and APP_URL’s in deploy/production.env.example, whose AUTH_CLIENT_URL becomes it too with make:auth (from the template’s https://app.example.com). Then, once main.go calls typescript.Register, it runs go run . types instead of templ generate. make:auth and make:crud run go run . types too in such a project, and make:auth after it points production’s AUTH_CLIENT_URL at APP_URL |
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 version | Prints 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. The names before v0.5, lang:add (or add lang) and make:admin:resource, are refused with the one to use
(locale:add, make:admin-resource) since v0.6; gen is one of
generate’s 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.) The names before v0.5, routes:list,
plugins:list, plugins:env and lang:check, are refused with the
one to use since v0.6. A command an app or plugin renames keeps its old
name in cmd.Command.Former, which runs it with a warning.
| Command | Added by | Does |
|---|---|---|
(none), run [--only=type,…] | every app | Runs the background components (all, or those of the process types web, worker, scheduler, listener, plus those without one) until SIGINT/SIGTERM (exit 0). Without --only, those of APP_PROCESS_TYPES when set |
serve | web.NewServer | run --only=web |
route:list [--json] | web.NewServer | Method, 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.Register | Writes 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 |
types [--check] | typescript.Register | Writes the frontend’s TypeScript types (in frontend/src/types, Config.Dir: api.ts always, pages.ts with Config.Inertia, routes.ts with Config.Routes), only the files that changed; --check exits 1 if one differs. Doesn’t boot the app, but needs its settings (APP_KEY). Since v0.6. See Generate TypeScript types for the frontend |
health:check [--live] [--timeout=5s] | web.NewServer | Asks 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.New | See the migrations reference; db:schema describes the tables: columns, indexes, foreign keys |
search:reindex [table…] | migrate.New | Rebuilds the search indexes (all, or the tables’) for DB_SEARCH_LANGUAGE and DB_SEARCH_RANKING. See Search |
ai:embed [table…] | ai.EmbeddingsFor | Embeds 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:clear | cache.New | Removes the app’s cache items (keys with CACHE_PREFIX), locks included |
queue:work | queue.New | Runs 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.New | List, 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.New | Publishes a message (its body as given) to a topic. See Pub/sub listeners |
locale:check [dir] | i18n.New | Reports 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.New | Each task, its schedule, its next run and options (--json: name, schedule, next, without_overlapping, on_one_server, timeout). See Scheduling |
schedule:run | schedule.New | Runs the tasks due this minute, once, with their locks, and exits: for cron or a Kubernetes CronJob every minute (it takes no arguments: schedule:test <task> runs one task) |
schedule:test <task> | schedule.New | Runs a task now, whatever its schedule (WithoutOverlapping applies, across processes only with a shared cache store; OnOneServer doesn’t) |
schedule:work | schedule.New | Runs only the scheduler, as run --only=scheduler |
rbac:roles, rbac:user <user-id>, rbac:assign [--scope=kind:id] <user-id> <role>, rbac:unassign … | rbac.New | List 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.Prunable | Deletes 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:prune | audit.New | Deletes the audit entries older than AUDIT_RETENTION_DAYS, and records that it did |
audit:anonymize <actor-type> <actor-id> | audit.New | Replaces 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.Load | Each 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.Load | The 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 app | Describes 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 app | Runs 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 app | Checks 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) |
version | every app | The 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, --help | every app | The 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 |
| API | Does |
|---|---|
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.| Check | Added by | Finds |
|---|---|---|
app | every app | In 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) |
db | db.Connect | In 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 |
migrations | migrate.New | After 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) |
session | session.New | SESSION_SECURE=false in production or staging (problem); SESSION_SAME_SITE=none (warning); SESSION_DOMAIN set (note) |
http | web.NewServer | HTTP_TRUSTED_PROXIES with 0.0.0.0/0 or ::/0 (problem) or a range wider than /8 (IPv4) or /16 (IPv6) (warning); HTTP_CLIENT_IP_HEADER without HTTP_TRUSTED_PROXIES (note); HTTP_CORS_ORIGINS=* (warning); in production and staging, an http:// or localhost origin in HTTP_SPA_ORIGINS (warning; since v0.6), HTTP_MAX_BODY, HTTP_REQUEST_TIMEOUT or HTTP_READ_HEADER_TIMEOUT set to 0 (warning) |
mail | mailer.New | MAIL_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) |
cache | cache.New | CACHE_DRIVER=memory in production or staging (note) |
queue | queue.New | In production and staging: QUEUE_DRIVER=memory (warning), sync (note) |
vite | vite.New | In development, public/build/manifest.json missing and VITE_DEV_URL not set: the pages load no scripts or styles of the frontend (warning; since v0.6) |
spa | vite.SPA | In production and staging with APP_URL: HTTP_SPA_ORIGINS not listing APP_URL’s origin, where the app serves its SPA (warning: the SPA’s login would answer a token). Since v0.6 |
| API | Does |
|---|---|
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.Problem | The severities: information; often a mistake; unsafe or broken (exit 1) |
env.Deployed() | Whether an anetos.Environment is production or staging |
db.Driver.InspectURL | For 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.
| Flag | Default | Meaning |
|---|---|---|
--level | basic | basic: the rules with few false alarms; advanced adds those that find what may be on purpose |
--format | text | text; 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 |
--out | the standard output | Writes the report to a file and prints the counts; - is the standard output |
--ignore | security-ignore.yaml | The 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 |
--strict | off | Exit 1 on a warning too |
--findings | none | A 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.
| API | Does |
|---|---|
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, OWASPLogging | OWASP 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.