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.
- The name is 2 to 63 lowercase letters, digits and dashes, starting with a letter and ending with a letter or digit, and no folder there may have it (E-CLI-002).
go.modrequires the framework version thisaicodedwas built with. Anaicodedinstalled withmake installin a framework checkout writes areplaceline to that checkout instead and says so.aicoded checkaccepts that line only from theaicodedinstalled from that very checkout, and refuses every otherreplace, anygo.workfile, avendorfolder, a module cache thatgo mod verifydoes not pass and every GOFLAGS entry outside the short list it allows (E-LINT-011); the delivery pipeline refuses areplaceline too (E-GATE-001), so require a released version before you publish. Anaicodedthat knows neither refuses (E-CLI-003).- When
go mod tidyfails, often for want of a network,aicoded initremoves the new folder (E-CHK-006).
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.
- It first runs lint's precheck for every app, before any other go command: GOFLAGS and a
vendorfolder decide what the go command builds and runs, so an app whose GOFLAGS orvendorfolder lint refuses (E-LINT-011) gets no other step. - For each app it runs
aicoded generateand lists the files it wrote, checks the snapshots the app holds, and runsgo build,go vet, lint andgo test; a step that fails skips the later steps of that app. Every problem has its code,file:line, fix and docs link (E-CHK-001 to E-CHK-008, and the E-LINT codes of lint). A go command that a signal stops, such as thego testthat a test kills, is E-CHK-008, with no position. - Lint applies the rules for app code to every file but the tests, and nothing in the code can
turn a finding off. Rules for app code lists each rule, what to do instead and its
E-LINT code. A file counts as generated, with what generated files may import and call, only
when
aicoded generatewrote it. When the go command is a newer Go than the oneaicodedwas built with, lint cannot read the code, and every app gets E-CHK-007. - Once lint has read an app, the report gives its surface, as
aicoded describedoes. - With
--frozenit writes nothing and reports every generated file that is out of date (E-CHK-001), as the security checks will. - The tests run with
-racewhen cgo works (go env CGO_ENABLEDis1and its C compiler is onPATH, as the first app that passes the precheck sees them); otherwise they run without it andchecksays so, since the delivery pipeline will run them with-race. They always run with-count=1: a result in the go command's test cache never stands for a run. - With
--no-testsit skips the tests and does not probe-race; every other step runs. The report says so:no_testsistruein JSON, and the text ends withtests did not run (--no-tests). Thechecktool ofaicoded mcpalways runs the tests. --jsonprints the same report as JSON.- It exits with 1 on any problem.
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:
pathandrequire, as theaccesssection of the permission list writes them;template, the route'sindex.htmlin the app folder;layout:truefor a layout with pages below it, which only redirects to one of them and has no entry in theaccesssection;params, the parameters of the URL in path order, each with itsnameand akindofnumber(ann_folder) orstring(ans_folder);guard:truewhen aGuardruns on the path;guard_atis the path of the route whose template declares the nearest one, or"";shared, as in theaccesssection;live:truewhen the page opens a live connection, because it or a layout above it has live values or page calls;calls, the page calls of the page and the layouts above it;forms, the forms of the route's own template, each with itsnameand itsfields:name,kind(input,file,textareaorselect),go_type,requiredandmultiple. Radio buttons or checkboxes that share a name are one field.
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.
- It prints the address of the sign-in: open it in a browser on this computer. You sign in with
your organisation's company login or, in an organisation that invites its builders, with the
account you were invited with. The browser then comes back to
aicoded, which listens for it on127.0.0.1only, and refuses an answer that does not belong to this sign-in. It waits 5 minutes (E-CLI-008).aicodeddoes not open the browser itself. - On a computer without a browser, such as a remote server, use
--device: it prints an address and a code instead. Open the address in a browser on any device, enter the code there, and confirm. The code expires after 10 minutes (E-CLI-008). - When the platform refuses you, the error quotes its reason (E-CLI-006). When you are not in your organisation's builder group, or not invited, ask your administrator to add you to it. When no organisation has the name you gave, check the name with your administrator.
- Ctrl-C stops the sign-in, and
aicoded loginprintssign-in cancelled. - It prints
Signed in to <organisation> as <email>.A new sign-in replaces and revokes the one before 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.
dirmust holdaicoded.yamland be the top level of a git repository with a commit (E-PUB-001), with nothing left uncommitted (E-PUB-002).--apprefuses an app of another name (E-PUB-003). It needs git 2.31 or later (E-PUB-012).- It runs
aicoded check --frozen --no-testsas a releasedaicodeddoes, and prints its problems and sends nothing when it finds any (E-PUB-004). - It sends a git bundle of the commit with its history since the app's last verified publish,
or all of it on the first publish, at most 32 MiB (E-PUB-009), with the app's name and a
summary:
-m, or the commit's subject. The first publish of a name creates the app, owned by you. - It sends the draft of schema changes,
.aicoded/migration.sql, with the commit, and refuses a commit that holds it (E-MIG-001). Once the publish passed, it deletes the draft, asaicoded statusdoes after--no-wait. See Schema changes. - It prints
Published <app> at <commit> as <id>., then waits for the outcome, asking every 3 seconds for up to 35 minutes, and prints the steps, the problems asaicoded checkprints them, the notes, which do not stop a publish, the decision on releasing a publish that passed, and the status. It exits with 0 when the publish passed and 1 otherwise. Ctrl-C stops the waiting, not the publish.--no-waitreturns at once, and says how to start the preview and release the publish once it passed. - The platform holds a publish that passed for your preview: the end of the waiting says
Held for preview, not live: its owner asks for its release with aicoded release <id>., then it starts the app's preview with the publish and prints it, asaicoded preview <id>does, with a line on what the preview does not do as production does, andIt is not live. When the app's owner asks for its release: aicoded release <id>.A preview that does not start is printed with its code, then what to do; the publish stays held, and the command exits with 0. See publishing. --releaseskips the preview: once the publish passed, it goes live by itself or waits for an approver, and the command says so after the id.aicoded publish --release --no-waitsends it and returns at once.--preview, from older versions, exits with 2: holding is the default.- When the platform refuses the sign-in for want of an app's scopes, or does not accept its
token, as when this computer's clock is off, it refreshes the sign-in once and asks again. That
is how a sign-in gets the scopes of the app its first publish created. A token the platform
still does not accept is E-CLI-004.
aicoded statusdoes the same.
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.
--envisprevieworproduction, and must be given; without itaicoded logsexits with 2. Production logs hold what the app logged while people used it: read them only to find out why something fails, and never copy them anywhere else.--sinceand--untilbound the time read: a time in RFC 3339, such as2026-10-24T09:00:00Z, or a while ago, such as30m,6hor2d. By default it reads the hour up to now. They may be at most 7 days apart (E-PUB-015), and the platform keeps 30 days.--levelkeeps the lines of that level or higher:DEBUG,INFO,WARNorERROR.--tracekeeps the lines of one trace.--limitis how many of the newest lines to read: 100 by default, at most 1000 (E-PUB-016).--jsonprints the lines as JSON, newest first, each with itstime,level,body,trace_id,span_id,release,envandattributes.- A value that is not valid is E-PUB-017, an app of another builder E-PUB-005, an archived app
E-PUB-006, an app that is not on the platform E-PUB-019, and a platform that cannot read logs
right now E-PUB-018. More rows than one answer holds, at most 16 MiB, is E-PUB-020: ask for
fewer, or a shorter time. A time whose rows the platform cannot read is E-PUB-021. Like
aicoded status, it refreshes your sign-in once when it lacks the app's scope.
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
- aicoded dev: running the apps.
- MCP: these tools for your AI assistant.
- Publishing: sending an app to the platform, and reading the outcome.
- Telemetry: what the logs and traces hold.
- The error catalogue: every code with its page.