@akterjs/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @akterjs/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Akter CLI, also published as [`akter`](https://www.npmjs.com/package/akter) so `npx akter` runs it.
+
+## Start
+
+```sh
+npx akter signup --email you@example.com      # emails a code; creates your account
+npx akter organizations create --name acme
+npx akter apps create --organization acme --name notes
+npx akter deploy --organization acme --app notes   # bundles src/app.layer.ts and deploys it
+```
+
+The CLI talks to Akter Cloud at `https://api.akter.dev` unless `--url` or `AKTER_CLOUD_URL` names another. `npx akter dev` runs your app on a local folder with no account, and `npx akter docs` prints these docs in the terminal. Agent apps can do the same through the MCP server at `https://mcp.akter.dev/mcp`.
+
+Docs: https://docs.akter.dev. Pricing: https://docs.akter.dev/pricing.
+
+## This package
+
+The `akter` command, built on `effect/cli`:
+
+- `akter dev`: the local engine on a folder (`.akter`), with the production layout and no cloud account. It serves the app's actors at `/rpc` and prints the URL. The app module (`--entry`, `<app>/src/app.layer.ts` by default) exports `app = { actors, layer }`: the actors to serve and their handler layers. A named export keeps the module within the house rules (`import/no-default-export`, `<name>.<role>.ts` file names), and an entry without an `app` export makes `akter dev` print what to export instead of starting. `akter dev` provides `Akter.local`, with those handlers, under `Akter.serve({ actors })`, which is the seam where Akter Cloud provides its own engine. It writes a small runner to `node_modules/.akter/dev.mjs` and runs it with `--watch` on whichever runtime started it, Bun or Node, so a source change restarts the server and keeps the data. On Node, the runner registers a resolve hook, so a relative import that ends in `.js` in a `.ts` file loads the `.ts` file it names, as TypeScript and Bun resolve it. `--reset` asks before it empties the folder; `--dir` moves the folder, and `--port` the port: without it, `akter dev` serves on `PORT` when that is set, which is how portless hands it one, and on 4000 otherwise.
+  - `/rpc` and the inspector answer only a loopback `Host` (`localhost`, 127.0.0.0/8, `[::1]`). `--allowed-host <name>`, repeatable, adds a name, for when you reach `akter dev` through a dev proxy or a tunnel that keeps its own hostname.
+  - `akter dev snapshots create|list|get|delete` and `akter dev environments list|get|branch|promote|delete`: snapshot, branch and promote the folder's environments, as Akter Cloud's `akter snapshots` and `akter environments` do for an app (`Akter.environments`, `serve/environment/` in `@akterjs/effect`). The folder starts with one environment, `dev`, whose store is the folder itself. `snapshots create --name <n>` records a Pending snapshot (`snapshot-<n>`, numbered from 0 and never reused) of the serving environment, or `--environment`'s, and the `akter dev` serving it takes it within a second: each actor's database copied with `VACUUM INTO` under that actor's command lock, and the files with it, into `<dir>/snapshots/<id>`. Until an `akter dev` serves that environment it stays Pending, as on Cloud. `delete` retires the record and removes the copy. `environments branch --name <b> --snapshot <n>` copies a Ready snapshot into `<dir>/environments/<b>`, quiet: `akter dev --environment <b>` serves its calls, but no timer fires, no outbox message is delivered and no job resumes until it is promoted; they are held, not dropped. `environments promote --name <b>` switches which environment the running `akter dev` serves, lifts the quiet, and prints what that leaves out: the writes made after the snapshot, or on a promote back, the writes the newer environment took. The environment it replaced is kept quiet and untouched until `environments delete`, which refuses the serving one and `dev` and keeps the name taken. A repeated promote changes nothing and prints the same result. Each command takes `--dir`, and `--json` prints Cloud's shapes. They run through a runner at `node_modules/.akter/environments.mjs`, like `history` and `migrate`, and aren't MCP tools: the registry and its MCP server cover Akter Cloud and an app's actor RPC, and this folder has neither.
+  - Beside `/rpc`, `akter dev` serves a read-only actor inspector on `127.0.0.1` at `--inspector-port` (`--port` + 1 when missing, any free port when `--port` is 0) and prints its URL. It lists the folder's actors by type, and for the one you open shows its state, its own tables (the first 100 rows of each), its command journal, pending timers, outbox, failed deliveries, jobs and files, updating every half second over server-sent events. It reads each actor's `actor.db` through `SqliteDriver.openQueryOnly` (`PRAGMA query_only = ON`), so it can't write, and it never creates an actor that doesn't exist yet (`Akter.inspector`, `serve/inspect/`). Like `/rpc`, it answers 421 to a `Host` that isn't a loopback name.
+- `akter deploy --organization <organization> --app <app> --url <control-url>`: bundle the same app entry as `akter dev`, upload it, confirm the build is Ready and start a deploy. It prints the Deploy actor's persisted notices once each, in order, until `Live` (exit 0), `NotServing` (exit 1, printing why the published build isn't serving) or `RolledBack` (exit 1). `--environment` defaults to `prod`; `--entry` selects the app module. `--organization` and `--url` fall back to `AKTER_ORGANIZATION` and `AKTER_CLOUD_URL`, then to the login `akter login` saved, and the key comes from `Credentials` (below) and needs deploy scope for that organization. The app must already exist. The CLI exchanges the key for a short-lived bearer token and refreshes it as needed; signed uploads use a separate client without that token. A timed-out or interrupted follow does not cancel the remote deploy. `--domain <hostname>` claims a custom hostname for the environment and prints the CNAME to add. Region selection is not a field in the current API.
+- Every other command of the release (accounts, keys, apps, files, computers, fork, branch, snapshot, restore, usage, billing, `docs`) is listed with its state in `../akter-cloud/docs/release-matrix.md`. Of those, every Cloud API endpoint is built as a registry command (below), and `docs`, `login` and `logout` are built; the rest wait for their endpoints.
+- `akter export --organization <organization> --app <app> --url <control-url> --out <folder>`: download every actor's database and history from Akter Cloud into `<folder>/shards/<shard>/<Actor>/<key>/actor.db`, the layout `akter dev` serves. Each `actor.db` is a decrypted, consistent SQLite backup holding the actor's state, tables, command journal, timers, outbox and jobs, and nothing else: no Cloud keys, export records or file grants. Each distinct file the actor's database names goes to `files/<sha256>` beside it, downloaded and checked before the database. It lists the app's 300 shards, 32 at a time, then exports their actors 4 at a time, printing each actor's lines whole and in shard order: it takes one snapshot per actor, downloads it in reads of at most 64 KiB with a progress line every MiB, and checks the SHA-256 and blanks the file grants before it renames the download to `actor.db`. Running it again with the same `--out` keeps finished actors and resumes a partial one from the same snapshot. An erased actor is skipped with a line saying so. A replaced, unauthenticated or mismatched snapshot deletes its partial download and exits nonzero. The server verifies a MAC over every page of the snapshot before it reports it, so a page rolled back within the snapshot stops the export; a rollback inside the live `actor.db` is outside that check. The key comes from `Credentials` and needs export scope.
+- `akter migrate --all`: apply pending migrations to every actor in the folder now, instead of on each actor's next open. It loads the same entry as `akter dev` and reads its `app` export, saying what to export when there is none, writes a runner to `node_modules/.akter/migrate.mjs` that calls `Akter.migrate`, and prints one line per actor with its old and new version (`Room "lobby": version 1 -> 2`). It stops at the first actor that fails, prints its type and key and why it failed (for a migration, its number and SQLite's message and code) and exits 1; the actors after it are left as they were. `--dry-run` prints the same lines without writing, and `--dir` and `--entry` work as they do for `akter dev`. Without `--all` it exits 2, since migrating a single actor isn't built yet. Against Akter Cloud it will run through the Cloud API once that exists.
+- `akter history <Actor>/<key>`: print an actor's command journal, oldest first, one line per command with its time, command, principal, payload and outcome (`-> ok` with the value, or `-> failed` with the command's typed error, such as `NotMemberError`). It loads the same entry as `akter dev`, writes a runner to `node_modules/.akter/history.mjs` and reads the folder through `Akter.local` and the actor's `historyStream`, which reads the journal 500 commands at a time, so a long history prints as it is read instead of being held in memory. `--json` prints one JSON object per command (`seq`, `at`, `command`, `commandId`, `principal`, `payload`, `outcome` and `value` or `error`), `--since 1h` keeps only the commands from that long ago until now (a whole number with `ms`, `s`, `m`, `h` or `d`), and `--dir` and `--entry` work as they do for `akter dev`. When `--since` or a history retention cuts the journal, the first line says from when it is complete (`complete since <time>`, or `{"coveredSince":"<time>"}` with `--json`), and the line repeats if a prune moves that time while the history prints. An actor name the app doesn't serve, a key its schema refuses or a malformed `--since` exits 2 and says why. `--verify` reruns the actor's kept history against the entry's current handlers through `Verify.replay`. It prints the window it replayed, then either `no difference` or the first command whose outcome differs, with its seq, command, command id and time and the expected and actual outcomes, and exits 1 when it finds one. `--json` prints the report as one JSON object, and `--verify` with `--since` exits 2, because replay starts from the actor's first command. When a history retention has pruned the start of the journal, `--verify` exits 1 and says from when the history is complete. Akter Cloud already serves an actor's history (`GET /v1/organizations/{organization}/apps/{app}/actors/{actor}/{key}/history`); this command doesn't call it yet.
+- `akter bench <workload>`: run a workload module (`export const workload = ({ id, kind, url }) => ({ name, open, step })`, where `kind` is `"local"`, `"cloud"` or `"comparison"`, so a workload sends a development identity such as `akter-principal` only to `akter dev`) against `akter dev` or an Akter Cloud app and print one row per outcome, failed steps included as `failed: <tag>`, each with steps, steps per second and p50, p90, p99 and max latency, plus the hardware, runtime, package versions, git commit and lockfile SHA-256. Without `--url` it starts `akter dev` on an empty temporary folder through a runner at `node_modules/.akter/bench.mjs`, and stops it after the run; `--url` takes a loopback `akter dev` someone else started, or any other URL as an Akter Cloud app: the CLI signs in with its credential (`AKTER_API_KEY`, else the key `akter login` saved) and passes the runner the session's bearer header on stdin, then the current one every 10 seconds, so a run longer than the 15-minute token keeps signing its steps. `--system <name> --url <url>` runs a workload against another system for comparison, such as `--system "Rivet actor"`: akter bench signs in to nothing, gives the workload no Akter client, and labels the report `COMPARISON RUN`. `--duration` (30s) and `--concurrency` (8) set the run, `--step-timeout` (30s) bounds the workload's `open` and each step, which counts as `failed: no answer within <ms> ms` when it runs out, and `--json` prints one JSON object. A local report starts with a `LOCAL RUN` notice and `"local": true`; a Cloud report starts with `AKTER CLOUD RUN`, says its latencies include the generator's network path and count only when the generator ran off the machine under load, and has `"local": false`. Cost per row is always `unmeasured`: the bench doesn't read the app's usage yet. The flash-sale and collab-doc examples run theirs with `pnpm bench`.
+
+- `akter <group> <operation>`: one command per Cloud API endpoint, derived at startup from the OpenAPI spec of `@akterjs/cloud-api` embedded by `generate` (`src/registry/`). The registry itself is `@akterjs/cloud-api/operations`, shared with Phase 12's MCP server: `operationsOf` turns each endpoint into an `Operation`: its command (`[kebab(group), kebab(name)]`, such as `apps delete`), its MCP tool name (`apps_delete`), its description, its fields (path, query and body properties, or one `payload` for a non-object body), a self-contained JSON Schema of its input and of its success body (component references rewritten to `$defs`), and its annotations: `readOnly`, `destructive`, `idempotent` and `openWorld`, defaulted from the HTTP method and overridden by the spec's `x-akter` extension, plus `confirm`, which defaults to `destructive`. Phase 12's MCP server builds its tools from the same list. `cloudCommands` gives each operation its flags plus `--input` (the whole input as JSON, `@file` or `-` for stdin), `--json` and `--url`; mutations add `--dry-run`, and operations that need a confirmation add `--approval`, sent as the `akter-approval` header. `OperationCall` validates the input against the operation's schema, asks `Approval` to confirm, signs in through `Credentials`, sends the request and checks the answer against the success schema before printing it. `tests/registry/cloud-commands.config.test.ts` fails when the embedded spec differs from the installed one, when an endpoint has no description or not exactly one command, or when a field's flag collides with another flag, and cloud-api's own tests check tool names, annotations and schemas; the streaming commands (`deploy`, `export`, `history`, `logs follow`) stay hand-written beside them. `akter logs follow` (`src/logs/`) is joined to the registry's `logs` group: it pages `logsRead` from the last cursor through the shared `Credentials` and `CloudClient`, retries what a retry may fix, and never prompts.
+- `akter actors <kind>` and `akter files <kind>`: the registry's other half, the operations on an app's actors, which go over the app's actor RPC (akter ADR 0016) rather than the Cloud API (`@akterjs/client/operations`, which also builds each request with `actorRequestOf`, so the CLI and the MCP server send the same one). `call` and `query` run a command or query (`--member`), `state` prints the actor's state once, `watch` prints a query's reply and each new one as JSON lines (`--count` stops it), `create` and `ensure` create an actor from `--payload`, and `fork` copies the actor into `--into` (a key, written like `--key`): over the actor RPC at a loopback `--url` (akter dev), and on any other target as the Cloud API's `actorForks.create`, which the Cloud registry serves as `actors fork`, with `--organization`, `--app`, `--environment` and `--approval`, confirmed and approved like every dangerous Cloud command (`src/registry/served-command.config.ts`); each has an MCP tool name (`actors_call` and so on) and annotations like the Cloud operations. They take `--actor`, `--key` (JSON, or a bare word as a string key), `--payload` (JSON) and `--url` (else `AKTER_APP_URL`), and mutations take `--dry-run` and `--command-id` (made when missing, so a retry runs once). `ActorCall` sends the request through `@akterjs/client`'s protocol with schema-free JSON payloads: a loopback URL (`akter dev`) needs no sign-in, and any other host gets the bearer token `Credentials` and `CloudClient` sign in for at the Cloud API, whose URL comes from `AKTER_CLOUD_URL` or `akter login`, since `--url` here is the app's. The actor's own errors print as the JSON it encoded (exit 1); the host's map to the exit codes below. `akter files <kind>` covers the file RPCs every actor's group carries, under a group of their own because the Cloud API has none: `list` and `usage` print a page of the actor's files (`--prefix`, `--cursor`, `--limit`), `download` writes a file's bytes to stdout (`--path`, and `--offset` with `--length` for a range; `--json` prints the RPC's base64 chunks instead), and a refusal prints and exits like any other, and `upload` sends `--content` (`@<file>`, `-` for stdin, or base64, as the `files_upload` tool takes it) through the open, append and close session in appends of at most 1 MiB and prints the receipt, which a command attaches at a path. `packages/client/tests/actor-operations.pure.test.ts` builds the RPC groups of real actors and fails when an RPC tag has no kind, and `tests/registry/actor-commands.config.test.ts` fails when an exposed kind lacks exactly one command or a tool distinct from every Cloud one; `warm` is deliberately not exposed, and the `computer` tags reserved for Phase 6 fail it until they are.
+- `akter login`, `akter signup`, `akter logout`: `Credentials` (`src/credentials/`) is the one place every Cloud command, hand-written or not, gets its key, URL and organization. The key is `AKTER_API_KEY` (an API key or agent key) when it is set and not empty, else the saved login: its secret in the OS keychain (`security` on macOS, `secret-tool` on Linux) or, when none is reachable, in `$XDG_CONFIG_HOME/akter/login.json` (`~/.config/akter/login.json`), written atomically with mode 0600 in a 0700 folder. A saved secret is bound to the origin it was saved for: `credentialFor(url)` refuses another origin with `LoginForOtherUrl` (exit 3), so a `--url` or `AKTER_CLOUD_URL` typed by mistake or planted in an agent's prompt can't receive it. `AKTER_API_KEY` goes only to `AKTER_CLOUD_URL`'s origin when that is set, and a `--url` naming another exits 2 with `ApiKeyForOtherUrl`; with no `AKTER_CLOUD_URL` it goes to whatever URL the command uses. `akter login --with-api-key` reads the key from stdin or a hidden prompt, checks it by exchanging it for a token, and saves it. `akter login --email <address>` (and `akter signup`, the same flow, since the first sign-in creates the account) wraps the sign-in endpoints through `CloudClient.anonymous`: it emails a code and prompts for it on a terminal, or, with no terminal, prints that the code was sent and exits 0, and `--code` finishes; the session's secret is saved as a key is and never printed. `tests/credentials/login.config.test.ts` runs both against scripted API replies.
+- `akter docs [topic]`: prints the pages of `apps/docs/content`, which `generate` embeds, as Markdown; `--json` prints one line of JSON.
+- Prompts: `Confirmation` (`src/terminal/`) asks only when stdin and stdout are terminals (`TerminalCapabilities.canPrompt`); otherwise it exits 4 at once, so a script or an agent never hangs on a question. `Approval` (`src/registry/approval.service.ts`) uses it for a registry command's confirmation, and turns the API's 428 `ConfirmationRequiredError` into an approval: at a terminal it requests the emailed code, asks for it, confirms it into a token and retries the command once with it; without one it exits 4 with reason `ApprovalRequired` and the `akter approvals` steps. The token is never printed.
+- Exit codes (`CliExitError.codes`): 0 done, 1 failed, 2 usage (and HTTP 400 or 422), 3 authentication (not signed in, HTTP 401 or 403), 4 confirmation or approval needed or declined (and HTTP 428), 5 unavailable (unreachable, timeout, HTTP 408, 429 or 5xx), 130 interrupted. With `--json`, a failure the CLI detects prints `CliExitError`'s JSON (`code`, `reason`, `message`) on stdout.
+- One program, two bins: `src/command/akter-program.config.ts` exports `runAkter`, which runs the command on the process's arguments, and `@akterjs/cli/program` exports it. This package's `akter` bin and the unscoped `akter` package's both call it, so `npx akter` is this CLI (ADR 0009). `akter --version` prints the package's version, which `generate` writes into `.generated`, so it follows the lockstep release version.
+- Startup: `pnpm build && pnpm measure:startup` times spawn to first output for local commands on Node and Bun (`scripts/measure-startup.cli.ts`); the target is p95 ≤ 300 ms.
+
+An operation behind a feature flag (its `x-akter` hint names one, akter-cloud ADR 0030) still runs when named, but is left out of help and unknown-command suggestions, as is a group whose every command is flagged. The baked-in spec cannot tell which flags an organization has; the Cloud API refuses an organization without the flag. This also applies to the joined `actors fork` command: Cloud forks are behind `cloudFork`, default off. A named fork at a loopback URL still works on `akter dev`, which has no flags. The MCP server hides `actors_fork` from everyone until it can read organization flags; it never falls back to the Cloud-forbidden actor RPC.
+
+Status: `akter dev`, `akter migrate --all`, `akter history` and `akter bench` on a local folder, `akter deploy`, `akter export` and the Cloud API commands against Akter Cloud, and `akter login`, `signup`, `logout` and `docs` are implemented. The other commands are not built yet.
+
+- Depends on: `effect` (peer) and `@effect/platform-node`. The app's project provides `@akterjs/effect`, which the runner imports, so the app and the engine share one copy.
+- Build-time input: the OpenAPI spec published by `@akterjs/cloud-api`, the Markdown in `apps/docs/content` and the package's version. `generate` invokes `@effect/openapi-generator`, writes the spec and the docs pages as modules beside the client, then compiles the generated source to the ignored `.generated/compiled` directory. Handwritten source and tests keep their strict Effect checks; the generated code is checked by TypeScript. The app manifest uses the SDK's shared contract description and migration hashing, rather than a second serialization.
+- Must not depend on: any private package.

package/dist/Argument-D81dqizB.mjs

@@ -0,0 +1,57 @@
+import { bn as dual } from "./Option-DkxSnBhp.mjs";
+import { _ as String$1, b as withDescription$1, v as argumentKind, y as optional$1 } from "./Command-Dzq9KM-h.mjs";
+// ../../node_modules/.pnpm/effect@4.1.2_patch_hash=0e61176203bb1256381ce1c5b488d7951983ce38ff698647d3f4617383abbf07/node_modules/effect/dist/cli/Argument.js
+/**
+* Creates a positional string argument.
+*
+* **Example** (Creating a string argument)
+*
+* ```ts import.meta.vitest
+* import { Argument } from "effect/cli"
+*
+* const filename = Argument.String("filename")
+* filename.kind // => "argument"
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 4.0.0
+*/
+const String = (name) => String$1(argumentKind, name);
+/**
+* Makes a positional argument optional.
+*
+* **Example** (Making an argument optional)
+*
+* ```ts import.meta.vitest
+* import { Argument } from "effect/cli"
+*
+* const optionalVersion = Argument.String("version").pipe(Argument.optional)
+* optionalVersion.kind // => "argument"
+* ```
+*
+* @stability unstable
+* @category combinators
+* @since 4.0.0
+*/
+const optional = (arg) => optional$1(arg);
+/**
+* Adds a description to a positional argument.
+*
+* **Example** (Adding an argument description)
+*
+* ```ts import.meta.vitest
+* import { Argument } from "effect/cli"
+*
+* const filename = Argument.String("filename").pipe(
+*   Argument.withDescription("The input file to process")
+* )
+* filename.kind // => "argument"
+* ```
+*
+* @stability unstable
+* @category combinators
+* @since 4.0.0
+*/
+const withDescription = /*#__PURE__*/ dual(2, (self, description) => withDescription$1(self, description));
+export { optional as n, withDescription as r, String as t };