aicoded.dev

Tools: the aicoded commands

aicoded creates apps, generates their code, checks them, describes them, explains its errors and docs, connects apps that call each other, signs you in to the platform, publishes apps to it and runs their previews there. Every problem it reports has a code, a file:line where there is one, a one-line fix and a docs link.

The commands

aicoded init <name>
aicoded generate [dir]
aicoded check [--frozen] [--no-tests] [--json] [--app <name>] [dir]
aicoded describe [--json] [--app <name>] [dir]
aicoded explain [topic]
aicoded rpc add <app>
aicoded dev [--manual <app>] [dir]
aicoded mcp [dir]
aicoded login [--org <organisation>] [--device]
aicoded logout
aicoded whoami [--json]
aicoded publish [--app <name>] [-m <summary>] [--release] [--no-wait] [dir]
aicoded status [--json] <id>
aicoded release [--no-wait] <id>
aicoded preview <id>
aicoded preview end [dir]
aicoded logs --env <env> [--app <name>] [--since <time>] [--until <time>] [--level <level>] [--trace <id>] [--limit <n>] [--json] [dir]
aicoded traces --env <env> [--app <name>] [--since <time>] [--until <time>] [--trace <id>] [--limit <n>] [--json] [dir]
aicoded version

dir is the current folder by default. aicoded exits with 0 when it succeeds, 1 when it reports a problem and 2 when the command line is not valid. aicoded dev has its own guide, aicoded dev, and aicoded mcp too, MCP.

aicoded init

aicoded init <name> creates an app in a new folder <name>: go.mod, a permission list with app: <name> and an audience of everyone in the company, main.go, one page and AGENTS.md, the rules for AI assistants that build the app. It then runs aicoded generate and go mod tidy.

aicoded generate

aicoded generate [dir] writes the generated files of the app in dir: the code of its pages, a dataprovider.go in a page folder that has none, the built assets, the server and snapshot of its rpc/ functions, the clients of the apps it calls, and the access and services sections of its permission list. aicoded dev, aicoded check and aicoded rpc add run it themselves. It needs go.mod next to aicoded.yaml (E-GEN-037).

aicoded check

aicoded check [--frozen] [--no-tests] [--json] [--app <name>] [dir] checks every app under the folder, or the one named.

ok  people
  surface 5 (5 entry points, 2 effects)
aicoded check: ok

aicoded describe

aicoded describe [--json] [--app <name>] [dir] summarises each app for your AI assistant: its app type, owner and audience, pages with their access rules, functions served and called, database, file stores, connectors, mail, outside services, scheduled jobs, settings, the names of its secrets, the modules it declares, its size, resources and review period, the tables its SQL writes, its surface, generated files that are out of date, and its local setup in dev.yaml, never a value of it: see aicoded dev. Each line shows only when the app has the item. It writes nothing. For the room-maintenance example, in a workspace whose dev.yaml names mysql: and one persona, it prints:

app room-maintenance (/home/me/apps/room-maintenance)
  class internal-tool
  owner group:hotel-ops-leads
  audience group:hotel-staff
  page /tickets  require staff
  page /tickets/report  require staff
  page /tickets/{id}  require staff  guard
  page /tickets/{id}/edit  require staff  guard
  page /tickets/{id}/status  require staff, hotel-ops  guard
  database
  size S
  resources small
  ttl 180d
  writes INSERT rooms, INSERT tickets, UPDATE tickets
  surface 5 (5 entry points, 3 effects)
  local workspace /home/me/apps
  local mysql set
  local persona alice  roles staff, hotel-ops  groups lisbon

The local lines come from dev.yaml, as aicoded dev run in the described folder uses it: the workspace it holds for that folder; local mysql set or not set, for an app that declares sqldb; each persona with its roles and groups, or local personas none when aicoded dev uses all-roles and no-roles; and local setting <name> set or not set, and the same for each secret, by name. When dev.yaml holds no workspace for the folder itself, local note: says what aicoded dev does then, and names the nearest folder above it that has one, whose values aicoded dev uses only when it runs there; when aicoded dev cannot read dev.yaml, local problem: gives the code, such as E-DEV-001.

An app with more in its permission list gets more lines, such as connectors crm after files, egress api.partner.example and schedule daily-summary cron 0 6 * * * after the mail, and external audience magic-link after audience. A page with an id in its URL shows guard or shared, as access explains: the people example prints page /users/{login}/info require staff shared.

--json prints the same summary as JSON, and the delivery pipeline builds its simulated attacks from it. Each app's pages hold what the lines above show, and its routes list every page and layout, sorted by path:

In the room-maintenance example, /tickets/{id}/status has "guard": true and "guard_at": "/tickets/{id}": the Guard of the ticket's page runs before the status page.

The surface is the app's size: the larger of its entry points and its effects. Its entry points are its pages, its page calls, counted once for each page that offers them, the functions it serves other apps and its scheduled jobs. Its effects are the tables its SQL writes, counted once for each of INSERT, UPDATE, DELETE and REPLACE, its connectors, the outside services it may call and the domains it may mail. The writes come from lint, which reads the SQL; when the app does not compile, or lint's precheck refuses its GOFLAGS or vendor folder, describe counts no writes and says so in a warning. Only INSERT, UPDATE, DELETE and REPLACE count, and a write to several tables counts its first table; a SELECT and a CREATE, ALTER or DROP of a table or index are not writes, and statements lint refuses outright, such as CALL, TRUNCATE, SET, PREPARE and EXECUTE (E-LINT-007), never reach the surface. Nothing compares the surface with size yet.

aicoded explain

aicoded explain <topic> prints a page of the docs built into aicoded: a guide such as guides/overview, a task recipe such as tasks/add-form, the changelog for AI assistants (changelog) or the page of an error code such as E-DEV-001. aicoded explain with no topic lists them all, with their titles. The pages are the same as in the repository's docs/ folder, and need no network. An unknown topic is E-CLI-001.

aicoded rpc add

aicoded rpc add <app>, in the folder of an app, lets it call the functions of the app named <app>: it copies that app's snapshot to .aicoded/services/<app>.json and generates the client services/<app>/client_gen.go. See calls between apps.

aicoded login

aicoded login [--org <organisation>] [--device] signs you in to the platform, as a builder of your organisation. The first login needs --org, the organisation's name on the platform, and later ones remember it.

To sign in to acme, open this address in a browser on this computer, or run aicoded login --device on a computer without one:

    https://api.aicoded.cloud/oauth/authorize?client_id=aicoded&...

Signed in to acme as ana@acme.example.

The sign-in lives in credentials.json in your user configuration folder, next to dev.yaml, with one entry per platform address. It works like a password: the file must have mode 600 and its folder mode 700, and aicoded refuses to use them while others can read them (E-CLI-007). Commands that use the sign-in at the same time take turns through credentials.lock, a file next to it, so that only one of them refreshes the sign-in and the others use the result; a command waits at most 30 seconds for its turn, and then fails with an error that names the file. AICODED_PLATFORM names the platform, https://api.aicoded.cloud by default; it must be an https address, with or without :443, or http://127.0.0.1:<port> for a platform on this computer (E-CLI-005).

There is no MCP tool for signing in: it needs a person and a browser.

aicoded logout

aicoded logout deletes your sign-in from this computer and asks the platform to revoke it. It deletes it even when the platform cannot be reached, and then says that the sign-in stays valid on the platform until it expires, within 30 days. It keeps the name of your organisation, so the next aicoded login needs no --org.

aicoded whoami

aicoded whoami [--json] prints the organisation, the email address and the scopes of your sign-in, as the platform sees them. It refreshes the sign-in first when it is about to expire; when the platform cannot refresh it right now, it fails with E-CLI-009 and keeps the sign-in. Without a sign-in, or with one the platform no longer accepts, it fails with E-CLI-004.

org: acme
email: ana@acme.example
scopes: app:create

aicoded publish

aicoded publish [--app <name>] [-m <summary>] [--release] [--no-wait] [dir] sends the commit HEAD names, of the app in dir, to the platform's delivery pipeline, which checks it and writes its change record. Publishing tells the whole story.

aicoded status

aicoded status [--json] <id> prints a publish as the end of aicoded publish does, at once: its steps, its problems, its notes, the decision on releasing it, with Live at <address> once the release is live, and its status, queued, running, passed, failed, refused or error. --json prints the publish as JSON, the address as release.url. It exits with 1 when the publish failed, was refused or ended in error. An id is pub_ and 26 lowercase letters and digits; another shape exits with 2. An id the platform does not know in your organisation is E-PUB-013, a publish of another builder's app E-PUB-005, and one of an app of yours that was archived E-PUB-006.

aicoded release

aicoded release [--no-wait] <id> asks for the release of the publish <id>, held for its owner's preview by aicoded publish; only the app's owner may. The platform decides again against the app type: the publish goes live by itself, waits for an approver, or is not released, with the reason. It then waits, as aicoded publish does, until the release is live, waits for an approver or ends otherwise, printing each state, such as going live ..., and prints the publish as aicoded status does; --no-wait prints it at once. It exits with 1 when the release was refused or failed. A publish that is not held, as one published with --release, is E-REL-037, and one that a newer publish of the app superseded E-REL-038; asking again for a release already asked for prints the publish as it is. An id is pub_ and 26 lowercase letters and digits; another shape exits with 2.

aicoded preview

aicoded preview <id> runs the publish <id> as its app's preview on the platform, and aicoded preview end [dir] ends the preview of the app in dir; see publishing. Only the app's owner may do either. aicoded preview <id> prints the preview's address and when it expires, in RFC 3339:

Preview of demo at https://demo.acme.preview.aicoded.cloud/ until 2026-11-13T10:00:00Z.
Invite up to five people in the console.

A publish that has not passed its checks is E-REL-029, and one whose permission list declares a setting or a secret with no value for the preview E-REL-030. An id is pub_ and 26 lowercase letters and digits; another shape exits with 2. aicoded preview end prints Preview of <app> ended; its data is being deleted., or exits with 1 and says that no preview of the app is running.

aicoded logs

aicoded logs --env <env> [dir] prints the log lines of an app on the platform, oldest first, as <time> <level> <text>, with trace <id> after a line that has a trace. It reads the app that aicoded.yaml in dir names, or the one --app names, with your sign-in, which must carry the app: you must own it.

Every read, and every refusal, is written to the platform's audit log: who asked for which app, the outcome, and the range and filters, never the lines.

2026-10-24T09:12:03.120Z INFO  page served
2026-10-24T09:12:04.007Z ERROR form failed: E-SQL-001  trace 4bf92f3577b34da6a3ce929d0e0e4736

aicoded traces

aicoded traces --env <env> [dir] prints the spans of an app on the platform, oldest first, each with its name, duration, failed and its status message when it failed, and its trace. With --trace <id> it prints the spans of that trace instead, indented below the span that holds them. It takes --app, --since, --until, --limit and --json as aicoded logs does, and refuses the same way. With --trace, --limit is how many of the trace's newest spans to read, 1000 by default. With --trace 4bf92f3577b34da6a3ce929d0e0e4736 it prints:

2026-10-24T09:12:04.001Z HTTP POST  12.4ms  failed: E-SQL-001
2026-10-24T09:12:04.003Z   sql.exec  9.1ms  failed: E-SQL-001

The control socket

One aicoded dev runs per workspace. It serves a control socket, control.sock with mode 600, in the workspace's private state folder under ~/.local/state/aicoded. aicoded mcp and a second aicoded dev talk to the running one through it: the second one refuses (E-DEV-012) and prints the login link of the running one's dev UI, and an aicoded of another version gets E-DEV-013. A file there that is not a socket (E-DEV-016), or a path too long for a Unix socket (E-DEV-017), stops aicoded dev.

Installing aicoded

go install aicoded.dev/framework/cmd/aicoded@latest installs the released aicoded, or @<version> that version, from v0.11.0 on; aicoded init writes that framework version into a new app's go.mod. make install, in a framework checkout, installs aicoded from it, with the path of the checkout built in for aicoded init.

See also

Markdown · Source on GitHub · framework f46741f