CLI reference

aps creates apistock apps, generates code in them and runs them locally. Decisions: ADR-0014 (presets and prompts), ADR-0021 (generator), ADR-0035 (interactive prompts with flag parity), ADR-0037 (aps add mail), ADR-0039 (aps gen resource).

Installing#

The library and CLI aren't published yet, so install aps from your checkout:

cd apistock/cli
go install ./cmd/aps

This puts aps in $(go env GOPATH)/bin (usually ~/go/bin). If your shell then says command not found: aps, add that directory to your PATH, for example in ~/.zshrc:

export PATH="$(go env GOPATH)/bin:$PATH"

Open a new terminal (or run hash -r) and check it works:

aps version

Run go install ./cmd/aps again after pulling changes.

Interactive or flags: both work#

Every command can be used two ways:

You can mix them: flags you pass skip their questions, and you're asked only for the rest.

aps new#

Creates an app.

aps new                                   # asks for everything
aps new my-api                            # asks for the rest
aps new my-api --module github.com/you/my-api --local ~/code/apistock --yes

Other flags: --skip-tidy (don't run go mod tidy), --json, --yes, --no-input, --plain.

Questions come one at a time. Each answered question folds into one line, and values you passed by flag are listed the same way, so every answer is on screen before the last question: create the app, yes or no.

✓ app name … shop-api
✓ Go module path … github.com/acme/shop-api
✓ preset … full
✓ tenancy … multi
✓ apistock checkout … /Users/you/code/apistock
✓ initialise a git repository? … yes
? create shop-api in ./shop-api? … yes  no

Then aps new prints a log: one line per finished step, where things are in the new app, and the commands to run next. --json prints only the result.

creating shop-api in ./shop-api
preset full · library ../apistock

✓ wrote 214 files
✓ ran go mod tidy
✓ initialised git

created shop-api

  api docs     http://localhost:8080/docs (localhost, not 127.0.0.1, for passkeys)
  emails       http://127.0.0.1:8025 (Mailpit catches every email in development)
  ...

  next: cd shop-api
        aps dev

A Full app is exactly examples/full-single with your name and module path (ADR-0041): its database, Compose project and service name are your app's name. With --tenancy multi it is exactly examples/full-multi instead: data belongs to organisations, with members, one role each, invitations, personal workspaces and org-scoped projects under /v1/orgs/{orgId}/… (ADR-0048). Tenancy is chosen at creation; aps add orgs turns a single-tenant app into a multi-tenant one later. After creating one:

cd my-api
cp .env.example .env
docker compose up -d --wait    # PostgreSQL and Mailpit
go run ./cmd/migrate
go run ./cmd/api               # or: aps dev

If port 5432 is taken, set POSTGRES_PORT in .env and the same port in DATABASE_URL. The app's README explains how to create the first admin and how to remove the examples.

Commit apistock.lock with the app. It records the aps release that created the app, the answers the templates used (name, module, preset, tenancy, email provider) and a SHA-256 of every file aps wrote except go.mod and go.sum. aps upgrade (v0.5) uses it to rebuild those files as they were and merge newer templates into your edits (ADR-0050). Don't edit it by hand.

aps gen job#

Generates a background job in an app created with the Full preset. The job's schedule, timeout and retries can be changed later in /ops/jobs without a deploy (background jobs guide).

aps gen job                                                     # asks for everything
aps gen job CleanupSessions                                     # asks for the rest
aps gen job CleanupSessions --schedule "0 3 * * *" --timeout 5m --max-attempts 5 --yes
aps gen job SendDigest --every 6h --description "Emails the daily digest." --disabled --yes
aps gen job RebuildIndex --on-demand --dry-run

Other flags: --dry-run (show the files, write nothing), --json, --allow-dirty (allow uncommitted changes), --yes, --no-input, --plain.

What it creates for CleanupSessions:

Safety checks: the app must have internal/app/jobs.go with the anchor; existing files are never overwritten; a job name can be registered once; the git repository must have no uncommitted changes (so the generated diff is easy to review) unless you pass --allow-dirty; generated Go is checked with gofmt.

aps gen resource#

Generates a module for records that belong to the signed-in user, in an app created with the Full preset: domain rules, use cases, a repository with hand-written SQL, /v1/<names> endpoints, tests and a migration. In a multi-tenant app (aps new --tenancy multi) records belong to an organisation instead: endpoints under /v1/orgs/{orgId}/<names>, every use case checks membership and a <module>.<resource>.read or .write permission with orgs.RequireMember, and the tests include non-members, roles without the permission and cross-organisation requests (ADR-0048). Everything it writes is your code to change (ADR-0039); examples/full-single/internal/modules/projects is exactly what it generates for the first example below, and examples/full-multi/internal/modules/projects what it generates there.

aps gen resource                                                        # asks for everything
aps gen resource Project name:string:unique description:text 'status:enum(active,archived)'
aps gen resource Person name:string bio:text --plural People --dry-run
aps gen resource Customer email:string:unique notes:text 'tier:enum(free,pro)' --json

Quote enum fields: shells treat parentheses specially.

Flags may come before, between or after the name and fields. Other flags: --dry-run, --json, --allow-dirty, --yes, --no-input, --plain.

Field names are snake_case (up to 20 characters). A resource needs at least one string field; the first one is its title. Names every resource already has (id, owner_id, org_id, created_by, version, created_at, updated_at, limit, cursor, sort, …) and PostgreSQL reserved words (order, user, …) are refused.

An org-scoped resource declares its <module>.<resource>.read and .write permissions in its internal/app/module_<names>.go, and the generator adds one line after //aps:anchor org-permissions in internal/app/permissions.go, so every organisation role gets them. Change which roles hold them in declareOrgPermissions.

What it creates for Project:

Then run go run ./cmd/migrate, go test ./... and go run ./cmd/api openapi > api/openapi.json.

Safety checks: the app must have internal/app/modules.go with the anchor inside errors.Join, the auth module and db/migrations; existing modules and files are never overwritten; a resource can be registered once; the migration always sorts after the existing ones; the git repository must be clean unless --allow-dirty; names and field types come from allowlists and generated Go names are checked for clashes, so no input reaches the code unchecked; generated Go is checked with gofmt.

aps gen migration#

Creates an empty SQL migration in an app created with the Full preset, for database changes that aren't a new resource: a column, an index, a data fix. (aps gen resource creates its own migration.)

aps gen migration add_customer_phone
aps gen migration AddCustomerPhone --dry-run      # the same file name; writes nothing
aps gen migration                                  # asks for the name

Other flags: --dry-run, --json, --allow-dirty, --yes, --no-input, --plain.

It creates db/migrations/<version>_add_customer_phone.sql with a short comment and an empty -- +goose Up section. The version is the current UTC time, such as 20260916083000, or one more than the newest migration's when that is later, so the new migration always runs last. There is no Down section: migrations only go forward (ADR-0005).

Then write the SQL under -- +goose Up, run go run ./cmd/migrate and go test ./... (tests migrate a fresh database with every file).

• Write the SQL before migrating. Goose records an empty migration as applied, so SQL added to it afterwards never runs.
• Edit it only until it is released. Locally, docker compose down -v resets a database that already ran it; once released, add a new migration instead.
• A statement that contains semicolons, such as a function body, goes between -- +goose StatementBegin and -- +goose StatementEnd.
• Don't write +goose in other comments: goose reads any comment line containing it as an annotation and rejects the file.

Safety checks: the app must have db/migrations; the name may only use letters, digits, hyphens and underscores (at most 60), so it can't reach a path or the SQL; an existing file is never overwritten; the git repository must be clean unless --allow-dirty.

aps add mail#

Sets up email in an app created with the Full preset: Resend or any SMTP server. Run it again to switch provider. Full walkthrough: email guide.

aps add mail                                             # asks for everything
aps add mail --provider resend --yes                     # Resend; add RESEND_API_KEY to .env yourself
aps add mail --smtp-host smtp.postmarkapp.com --smtp-username <token>   # SMTP; asks for the password
aps add mail --provider smtp --dry-run                   # show what would change

Secrets are the one exception to "every question has a flag": they would end up in shell history. Type them at the hidden prompt, or put them in .env or the environment.

Other flags: --dry-run, --json, --allow-dirty, --skip-tidy (don't run go mod tidy), --yes, --no-input, --plain.

What it changes:

After confirming, it prints numbered next steps: where to get the Resend key and verify your domain (or which SMTP variables are left), how to set the sender with PUT /ops/settings/mail.from_email, and how to send a test email with POST /ops/mail/test. The sender name, address and reply-to are runtime settings, so they're never asked here.

Safety checks: the app must have internal/app/mail.go and the .env.example block; the git repository must be clean unless --allow-dirty; .env must be ignored by git before a secret is saved in it; secret values are never printed or included in --json output. Running it with the provider already in place changes nothing.

aps add orgs#

Turns a single-tenant Full app into a multi-tenant one, on branch aps-add-orgs: organisations with members, one role each, invitations and personal workspaces, and projects under /v1/orgs/{orgId}/projects (ADR-0048, ADR-0050).

aps add orgs --dry-run     # what would change, per file
aps add orgs               # apply on branch aps-add-orgs

It merges the multi-tenant app's files into yours the way aps upgrade merges a release: files you never edited are replaced, your edits are merged or shown as conflicts. Then it adds two migrations after your existing ones:

Without conflicts it updates go.mod, builds, regenerates api/openapi.json and commits Add organisations. Then run go test ./..., apply the migrations (aps dev, or go run ./cmd/migrate in each environment) and merge the branch. Set orgs.invitation_url before inviting people.

Resources you generated with aps gen resource stay owned by users and keep working; the command lists them. To move one to organisations, generate it again with --scope org and move its data.

Other flags: --json, --skip-tidy, --skip-build. Safety checks: the app must be in git with no uncommitted changes, and on this release (run aps upgrade first). An app that already has organisations is left alone.

aps upgrade#

Brings the files aps wrote into your app up to this release, on a branch, without losing your edits (ADR-0050).

aps upgrade --dry-run          # what would change, per file; writes nothing
aps upgrade                    # apply on branch aps-upgrade/<version>
aps upgrade --from v0.4.0      # apps created before v0.5 name the release that created them

It rebuilds every file exactly as the release recorded in apistock.lock wrote it, checks each against the hash in the lock, and merges per file:

A file whose rebuilt content doesn't match the lock is compared as yours against the release, so it can conflict but is never overwritten. Migrations are never merged: new ones are added with their released names, and yours stay as they are. Files aps gen created aren't tracked, so they're never touched.

Without conflicts it then updates go.mod (new requirements and the new library version, then go mod tidy), runs go build ./..., regenerates api/openapi.json and commits Upgrade apistock to <version>. Run your tests (database tests need aps dev or docker compose up -d --wait) and merge the branch. With conflicts it exits with code 1, commits nothing, and lists the files to resolve and the commands to finish.

Where earlier releases come from: with an apistock checkout (--local, the checkout your go.mod replaces the library with, or the one you run in), git archive of the release's tag or commit. Otherwise the apistock.dev/cli module from the Go module proxy, verified by the checksum database: aps upgrade refuses when GOSUMDB=off or GONOSUMDB, GOPRIVATE or GOINSECURE covers it. Templates are only rendered as text; nothing downloaded is run.

Safety checks: the app must be in git with no uncommitted changes, and the branch aps-upgrade/<version> must not exist yet.

aps dev#

Builds and runs the app in the current directory, rebuilding when files change and loading .env (variables already set in the environment win).

In an app with a database (Full preset), before the first start it:

1. Creates .env from .env.example (mode 0600) when there is none, and fills an empty AUTH_ENCRYPTION_KEYS with a random development key (ADR-0043).
2. Checks Docker, and that the services' host ports are free: POSTGRES_PORT, MAILPIT_SMTP_PORT and MAILPIT_WEB_PORT (ports held by the app's own running services are fine). A taken port names the .env line that moves it.
3. Starts PostgreSQL and Mailpit from the app's compose.yaml with docker compose up -d --wait.
4. Applies migrations (go run ./cmd/migrate) and runs seed data (go run ./cmd/seed). The first run prints the administrator's password once (ADR-0042); later runs change nothing.
5. Prints the API, docs and email inbox addresses, then starts the app.

While it runs, a changed or new migration is applied before the restart; if it fails, the previous version keeps running. Services keep running after aps dev stops, so the next start is fast: docker compose down stops them, and docker compose down -v also deletes the database.

Without Docker, a Full app stops with a message: install and start Docker, or point DATABASE_URL at an existing PostgreSQL and use --no-services. Without the CLI, the same steps are cp .env.example .env, docker compose up -d --wait, go run ./cmd/migrate, go run ./cmd/seed and go run ./cmd/api.

Exit codes#

JSON output#

--json prints only a machine-readable result on stdout and never prompts.

{"name": "SendDigest", "definition": "send_digest", "files": ["internal/jobs/senddigest/senddigest.go", "…"], "dry_run": false}

Commands, flags, exit codes and JSON fields are public API from CLI 1.0 (ADR-0015).