YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
CLI Reference▾
AkanJS Reference▾
Application CLI
These commands carry an app from creation to release: create it, run it locally, check and build it, then ship it as a native app.
Manage Apps
CommandDescription
Create a new app under
apps/ from the template.Delete an app's folder from the workspace.
Regenerate the generated files of an app or library.
List the files an app needs to move into a workspace of its own.
Local Development
CommandDescription
Run the dev server for one or more apps.
Start the local database containers.
Stop the local database containers.
Run a file from the app's
script/ folder.Open an interactive server console.
Follow a running app's logs, filtered.
Check and Build
CommandDescription
Typecheck the app.
Run the tests of an app, library or package.
Build the app for production into
dist/apps/<app>.Native
CommandDescription
Run the app on a simulator, an emulator or a connected device.
Run the app as a desktop app on this computer.
Build the native app on the native runtime.
Build the app for an App Store or Play Store release.
Sign and publish releases installed apps update themselves to, or pack a phone update for a signer elsewhere.
create-application
Create
apps/<appName> from the app template, then sync it. With --start it also boots the dev server.Signature
Arguments
appNameStringrequired
App name. It is lowercased, and spaces become hyphens.
Options
--startBooleandefault false
Start the dev server and open the browser once the app is created.
Examples
remove-application
Delete the
apps/<app> folder, so the app drops out of sync, builds and deployment. Commit first if you may want it back.Signature
Examples
sync
Rescan an app or library and rewrite its generated files. Run it after adding, renaming or deleting a file, or after changing its imports.
Signature
Notes
NameDescription
generated files
Barrels like
index.ts, cnst.ts and st.ts, akan.<app|lib>.json, and the scoped AGENTS.md.dependencies
Each package the code imports is written into its own
package.json, at the root's version.apps only
Also links lib assets into
public/libs and, with syncPageLibs, lib routes into page/(libs).run for you
start, build, typecheck and test run it first through --write.Examples
plan-slice
Print the exact files an app needs to live in a workspace of its own. It only prints the plan and writes nothing.
Signature
Options
--formatStringdefault texttext | json
Output format.
Notes
NameDescription
contents
The app, every lib it reaches, the workspace shell around them, and a root
package.json.file source
Files come from git, so gitignored files such as env values are left out.
root manifest
Keeps only the packages the slice imports, at the workspace's own version specs.
warnings
Untracked files under the app or its libs are listed, because git would not carry them.
Examples
start
Run the dev server, SSR frontend and backend together. Name apps space- or comma-separated, pass
all, or leave them out to tick them in a checklist. Several apps share one session.Signature
Options
--plainBooleandefault false
Print prefixed, interleaved lines instead of the full-screen view.
--killBooleandefault false
Free the dev ports first. A holder that is not an akan process is reported and left alone.
--concurrencyNumber
Apps booted at a time. Unset: the lower of half the memory ÷ 1.8GB and cores ÷ 4.
--dbupBooleandefault true
Start the local services of the mode each app runs in first. On exit it stops only what it started.
--openBooleandefault false
Open the app in the browser.
--shareBooleandefault false
Also publish each app on a public URL through an akan tunnel.
s in the view copies it.--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan s runs this command.plain output
A pipe, a redirect or a terminal with no size switches to
--plain on its own.session log
Each app writes
local/apps/<app>/runtime/dev.log, except one app under --plain.memory budget
AKAN_MEMORY_LIMIT lowers the memory --concurrency is derived from.Examples
dbup
Start the local database services with Docker Compose: Redis for
multiple, Redis and Postgres 18 for cluster. akan start already runs it unless --dbup false.Signature
Options
--modeStringsingle | multiple | cluster
Start one mode's services;
single needs none. Left out, every mode the workspace's apps declare.Notes
NameDescription
Docker
Needs a running Docker daemon. Services already running are left as they are.
compose file
local/docker-compose.yaml is written on first use and then left to you.missing service
An older compose file may lack one. Add it, or move the file aside to get the current template.
Examples
dbdown
Stop the local database with
docker compose down in local/. Every service of that compose project stops, whichever app started it.Signature
Examples
db-export
Write every model table of the app to one NDJSON file each, from the database of the mode the shell names. Pair it with
db-import to move data between modes, such as single to cluster.Signature
Options
--dirStringdefault local/transfer
Folder to write the files into, relative to the workspace root.
Notes
NameDescription
mode
The shell's
AKAN_DATABASE_MODE, or the app's first declared mode.deployed data
For a deployed
single app, copy its SQLite file and point SQLITE_DATABASE_PATH at the copy.no traffic
Boots the app without listening and without running cron or init jobs.
Examples
db-import
Read the files
db-export wrote into the database of the mode the shell names. The app must declare that mode.Signature
Options
--dirStringdefault local/transfer
Folder to read the files from, relative to the workspace root.
Notes
NameDescription
rows
Rows move as stored, removed ones included. An existing id is replaced, so a rerun is safe.
text search
The search index is rebuilt after the import.
not moved
Sessions and queued jobs stay behind, so users sign in again. Copy uploads in
local/ yourself.no traffic
Boots the app without listening and without running cron or init jobs.
Examples
script
Sync the app, then run
apps/<app>/script/<filename>.ts with Bun. Leave the filename out to pick one from a list.Signature
Arguments
filenameString
A file directly in
script/; the .ts suffix is optional. Subfolder paths are refused.Examples
console
Open an interactive console for inspecting the app's services and data at runtime.
akan build also writes console.js beside main.js, so the same console runs inside a container.Signature
Notes
NameDescription
process
Boots a separate server with no traffic and no internal jobs; it never attaches to
main.js.globals
srv, sig, db, cnst, dict and option are ready at the prompt.container
Run
AKAN_CONSOLE=1 bun console.js inside a built container or pod.production
Refused under
main env, cloud/edge mode or NODE_ENV=production unless AKAN_CONSOLE=1.Examples
logs
Follow a running app's logs through its
akan-control.sock. Every record carries the traceId, endpoint and origin of its call, so you filter by call rather than by text alone.Signature
Options
--levelStringtrace | verbose | debug | info | warn | error
Lowest level to print.
--grepString
Text the message must contain.
--endpointString
Endpoint globs, comma-separated:
mutation:*, query:userList.--traceString
One request's traceId; collects every line that request wrote.
--childString
Replica indexes, comma-separated.
--roleString-R
Process roles:
gateway, federation, batch, all, rsc-worker.--originString
Call origins:
http, websocket, mcp, internal, page.--sinceString
Only newer records:
30s, 5m, 2h, 1d, or epoch ms.--replayNumberdefault 0-n
Buffered records to print before following. With
--follow false it caps the history.--jsonBooleandefault false
Print NDJSON records instead of rendered lines.
--followBooleandefault true
Keep streaming.
--follow false prints the history and exits.--runtime-dirStringdefault local/apps/<app>/runtime-d
Folder holding
akan-control.sock. Without it, AKAN_RUNTIME_DIR and then the default apply.Notes
NameDescription
in the console
akan console has the same filters as .tail and .trace <id>.Examples
typecheck
Typecheck the app with TypeScript. It reuses an incremental cache, which
--clean clears first.Signature
Options
--writeBooleandefault true
Run
akan sync first so generated files are current.--cleanBooleandefault false
Delete the incremental cache (
tsconfig.tsbuildinfo) before checking.--incrementalBooleandefault true
Reuse the TypeScript incremental cache.
Notes
NameDescription
alias
akan t runs this command.Examples
test
Prepare an app, library or package, then run its tests with
bun test --isolate in that folder.Signature
Options
--writeBooleandefault true
Sync an app target first. Libraries and packages are always prepared.
Examples
build
Build the app for production into
dist/apps/<app>. It typechecks, then compiles the backend, the SSR routes and the CSR bundle.Signature
Options
--writeBooleandefault true
Run
akan sync first so generated files are current.--fastBooleandefault false
Skip the typecheck step.
--quietBooleandefault false
Hide the progress output and the build summary.
Notes
NameDescription
alias
akan b runs this command.web surfaces
The SSR and CSR steps follow
web in akan.config.ts; a surface turned off is skipped.Examples
start-ios
Run the iOS app on a simulator or a paired iPhone. By default it is a debug build whose pages come from your local dev server;
--release runs a release build of its own bundle instead.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault locallocal | debug | develop | main
Backend environment the app connects to.
--releaseBooleandefault false
Run a release build that carries its own production web build instead of loading the dev server.
--deviceString
The simulator, emulator or device to run on: its id or name, such as
iPhone 17 or Pixel_10. A paired iPhone's name makes a signed iPhone build. Left out, a booted iPhone simulator (else the newest one) or a connected Android device (else the first emulator, started) is used.--teamString-T
The Apple team id the signing is narrowed to, when the Mac holds profiles of several teams.
--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan si runs this command.dev server
Without
--release the app loads its pages from akan start <app> through the dev gateway, so every save shows up; keep the dev server running, or the command stops and says so.one target
Runs one native target at a time; with several, pass
--target <name>.output
A dev build goes under
dist/native/<app>/<target>/dev/ios; a --release run under …/build/ios.Examples
start-android
Run the Android app on an emulator or a connected device. It works like
start-ios: the dev server by default, a bundled release build with --release.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault locallocal | debug | develop | main
Backend environment the app connects to.
--releaseBooleandefault false
Run a release build that carries its own production web build instead of loading the dev server.
--deviceString
The simulator, emulator or device to run on: its id or name, such as
iPhone 17 or Pixel_10. A paired iPhone's name makes a signed iPhone build. Left out, a booted iPhone simulator (else the newest one) or a connected Android device (else the first emulator, started) is used.--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan sa runs this command.dev server
Without
--release the app loads its pages from akan start <app> through the dev gateway, so every save shows up; keep the dev server running, or the command stops and says so.one target
Runs one native target at a time; with several, pass
--target <name>.output
A dev build goes under
dist/native/<app>/<target>/dev/android; a --release run under …/build/android.Examples
start-desktop
Run a native target as a desktop app on this computer: macOS, Windows or Linux, whichever it is, since a desktop app builds only on its own OS. It works like
start-ios, with no device or team to pick.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault locallocal | debug | develop | main
Backend environment the app connects to.
--releaseBooleandefault false
Run a release build that carries its own production web build instead of loading the dev server.
--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan sd runs this command.dev server
Without
--release the app loads its pages from akan start <app> through the dev gateway, so every save shows up; keep the dev server running, or the command stops and says so.a server without --release
For a target that carries its server, a dev server already answering on the app's dev port is used as it is. Otherwise
akan start <app> runs in the same command, the app opens once it serves, and Ctrl+C or closing the app stops both. --env does not reach the dev server, which follows the workspace .env.desktop.server
With
native: { desktop: { server: true } } in akan.config.ts, or desktop.server in one target, the desktop app carries the app's server: it starts beside the window on a loopback port and the pages call nothing else. build-desktop, start-desktop --release and publish-update all read it. An installed app refuses an update that adds or drops the server, so turning it on or off for an app already out there takes a reinstall.carried server
An API-only server on the app's own Bun, bound to 127.0.0.1. Any program on the computer can call it, so guard its endpoints as a network server's. The app needs
single in database.modes, and the data stays in the app data folder's server/. It carries private/ (each lib's too), the --env's env.server.<env>.ts and the libs' server env defaults in plain text, so keep secrets and license files out of them. It has no public/ and runs in its data folder: read runtime files from AKAN_APP_DIR, never process.cwd(). It runs none of the image's docker steps; a package that builds itself at install goes in trustedDependencies.bin
An executable
bin names in akan.config.ts is fetched for this computer and carried in every desktop app, whether or not it carries a server: it is first on the app's PATH, so the carried server's spawn("ffmpeg") runs it, and a native plugin finds it in ctx.binDir.one target
Runs one native target at a time; with several, pass
--target <name>.output
A dev build goes under
dist/native/<app>/<target>/dev/<macos|windows|linux>; a --release run under …/build/<macos|windows|linux>.Examples
build-ios
Build the iOS app on the native runtime. It first makes a production web build against
--env, then builds a simulator app for each target.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault debuglocal | debug | develop | main
Backend environment the app connects to.
--debugBooleandefault false
Make a debug build instead of a release one.
--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan bi runs this command.output
Written under
dist/native/<app>/<target>/build/ios; the command prints each file's path.Examples
build-android
Build an APK of the Android app on the native runtime. Like
build-ios, it makes a production web build against --env first.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault debuglocal | debug | develop | main
Backend environment the app connects to.
--debugBooleandefault false
Make a debug build instead of a release one.
--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan ba runs this command.signing
Signed with
~/.akan/native/debug.keystore, which is fine for testing; a Play Store file comes from release-android.output
Written under
dist/native/<app>/<target>/build/android; the command prints each file's path.Examples
build-desktop
Build the desktop app on this computer's OS: a
.app on macOS and an app folder on Windows and Linux. Like build-ios, it makes a production web build against --env first. A release build signs from the environment — a Developer ID with notarization on macOS (AKAN_NATIVE_MACOS_*), Authenticode on Windows (AKAN_NATIVE_WINDOWS_*) — and warns when it cannot, since a downloaded copy is blocked or flagged. See the Desktop Release cheatsheet.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault debuglocal | debug | develop | main
Backend environment the app connects to.
--debugBooleandefault false
Make a debug build instead of a release one.
--installerBooleandefault false
Also what a person downloads: on Windows
<file>-<version>-<arch>-setup.exe with NSIS (winget install NSIS.NSIS), on macOS a .dmg, on Linux an .AppImage (needs mksquashfs).--archStringdefault this computer's
The CPU a Windows or Linux app runs on:
arm64 or x64. The server's addons and bin follow it. A macOS app is Apple silicon (arm64) only.--writeBooleandefault true
Run
akan sync first so generated files are current.Notes
NameDescription
alias
akan bd runs this command.desktop.server
With
native: { desktop: { server: true } } in akan.config.ts, or desktop.server in one target, the desktop app carries the app's server: it starts beside the window on a loopback port and the pages call nothing else. build-desktop, start-desktop --release and publish-update all read it. An installed app refuses an update that adds or drops the server, so turning it on or off for an app already out there takes a reinstall.carried server
An API-only server on the app's own Bun, bound to 127.0.0.1. Any program on the computer can call it, so guard its endpoints as a network server's. The app needs
single in database.modes, and the data stays in the app data folder's server/. It carries private/ (each lib's too), the --env's env.server.<env>.ts and the libs' server env defaults in plain text, so keep secrets and license files out of them. It has no public/ and runs in its data folder: read runtime files from AKAN_APP_DIR, never process.cwd(). It runs none of the image's docker steps; a package that builds itself at install goes in trustedDependencies.bin
An executable
bin names in akan.config.ts is fetched for this computer and carried in every desktop app, whether or not it carries a server: it is first on the app's PATH, so the carried server's spawn("ffmpeg") runs it, and a native plugin finds it in ctx.binDir.installer
It installs for the current user under
%LOCALAPPDATA%\Programs, where updates swap the app without an administrator, and adds the WebView2 Runtime where it is missing. /S installs silently and /RUN starts the app afterwards.reinstall
/D=<folder> picks the install folder. Run again without it, the setup installs where the app already is; one started while another runs refuses to start.output
Written under
dist/native/<app>/<target>/build/<macos|windows|linux>; the command prints each file's path.Examples
release-ios
Build and sign the iOS app for an App Store release: an iPhone app and its
.ipa. It defaults to the main backend and refuses --env local unless --allow-local-release is passed.Signature
Options
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault maindebug | develop | main | local
Backend environment the app connects to.
--teamString-T
The Apple team id the signing is narrowed to, when the Mac holds profiles of several teams.
--ad-hocBooleandefault false
Sign with an ad-hoc profile instead of an App Store one.
--writeBooleandefault true
Run
akan sync first so generated files are current.--allow-local-releaseBooleandefault false-l
Allow a release built with
--env local.Notes
NameDescription
signing
The certificate and profile are found among the ones Xcode keeps on this Mac: the profile must cover the app id and every capability the app asks for. The command prints the one it used.
output
Written under
dist/native/<app>/<target>/build/ios; the command prints each file's path.Examples
release-android
Build and sign the Android app for a Play Store release, as an AAB or an APK. Like
release-ios, it defaults to main and refuses --env local without --allow-local-release.Signature
Options
--assemble-typeStringdefault aabaab | apk
aab for a Play Store upload, apk for direct installs.--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault maindebug | develop | main | local
Backend environment the app connects to.
--writeBooleandefault true
Run
akan sync first so generated files are current.--allow-local-releaseBooleandefault false-l
Allow a release built with
--env local.Notes
NameDescription
signing
Signed with the upload key the environment names:
MYAPP_RELEASE_STORE_FILE, MYAPP_RELEASE_STORE_PASSWORD and MYAPP_RELEASE_KEY_ALIAS, plus MYAPP_RELEASE_KEY_PASSWORD when the key has its own. A missing one stops the command before it builds.output
Written under
dist/native/<app>/<target>/build/android; the command prints each file's path.Examples
update-keygen
Make, once per app id, the Ed25519 key update releases are signed with, and print its public key for
native.updates.publicKey. Run again, it reads the key it made. The key lives in ~/.akan/native/keys/<app id>.update.key, or where AKAN_NATIVE_UPDATE_KEY points: keep it in the secret store the release machine reads, since an installed app takes no release it cannot verify. An appId that differs per platform has a key per id, so name the --platform you publish for.Signature
Options
--platformStringdefault desktopdesktop | android | ios
The platform whose app id the key signs for.
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.Examples
publish-update
Build a release and sign it for installed apps: the whole app for a desktop (this computer's OS and CPU, delta from the release before), the web bundle for Android and iOS. It writes
<channel>.json, its signature and its files under dist/native/<app>/<target>/updates, which holds only what you upload: upload that folder to native.updates.url, <channel>.json and its .sig last and together, and keep a CDN from caching those two apart. A desktop release of a target that carries its server carries it too.Signature
Options
--platformStringdefault desktopdesktop | android | ios
desktop is this computer's own OS and CPU.--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault maindebug | develop | main | local
Backend environment the app connects to.
--channelString
Default
updates.channel, else --env. It names only the manifest written, not the channel the release follows.--writeBooleandefault true
Run
akan sync first so generated files are current.--allow-local-releaseBooleandefault false-l
Allow a release built with
--env local.Notes
NameDescription
desktop.server
With
native: { desktop: { server: true } } in akan.config.ts, or desktop.server in one target, the desktop app carries the app's server: it starts beside the window on a loopback port and the pages call nothing else. build-desktop, start-desktop --release and publish-update all read it. An installed app refuses an update that adds or drops the server, so turning it on or off for an app already out there takes a reinstall.--env
An app takes releases on
updates.channel, else on the --env it was built with: publish with that --env.pilot
A release keeps its build's channel: give a pilot group a target whose
updates.channel is the pilot's.server change
Refused before it builds when the channel's last release differs in carrying a server, as installed apps would refuse it: publish on another channel (
updates.channel) or remove its <channel>.json from the output folder to start over.readable
Anyone who reaches
updates.url can read the release; the updater sends no credentials. A desktop release is the whole app, the carried server's private/ and env file included.Examples
pack-update
Pack an Android or iOS web bundle update unsigned, for a signer that keeps the key off this machine:
files/<sha256>, bundle.json and manifest.template.json, the manifest with channel, sequence and bundle left for the signer, who signs exactly the bytes it uploads and uploads files/ first. publish-update does the same with a key on this machine.Signature
Options
--platformStringios | android
The app it updates.
--targetString
A key of
native.targets in akan.config.ts, or all. Asked for when there are several.--envStringdefault maindebug | develop | main | local
Backend environment the app connects to.
--outString
Default
dist/native/<app>/<target>/updates/<platform>.--againstString
The
bundle.json of the store build it must run in: writes compat.json, and fails when the bundle needs a new binary.--writeBooleandefault true
Run
akan sync first so generated files are current.--allow-local-releaseBooleandefault false-l
Allow a release built with
--env local.Examples
Rules Every Command Shares
- Choosing the app.
<app>is a folder name underapps/. Leave it out and the CLI asks you to pick, or takes the only app there is. - Boolean options.
--faston its own means true. To turn an option off, give the value:--write false. - Short flags. Each option also answers to its first letter (
-wfor--write) unless its row shows another.--verbose(-v) works on every command. --writeruns sync first. It is on by default, so generated files are fresh before the command runs.--write falseskips it.- The database mode.
start,build,script,console,db-exportanddb-importuse the shell'sAKAN_DATABASE_MODE, which must be one the app declares, or else its first declared mode.
Short Names
| Short name | Runs |
|---|---|
| akan b | akan build |
| akan t | akan typecheck |
| akan s | akan start |
| akan bi | akan build-ios |
| akan ba | akan build-android |
| akan bd | akan build-desktop |
| akan si | akan start-ios |
| akan sa | akan start-android |
| akan sd | akan start-desktop |