# CLI Every `npx @aozumi/fold` command, and whether it works today. Run commands with `npx @aozumi/fold ` (Node 20 or newer). There is nothing to install. Most commands take an optional fold directory and default to the current one. `--help` prints the full usage. ## Status at a glance | Command | Status | |---|---| | `new`, `create`, `init` | Works | | `dev`, `run-many` | Works (local) | | `build` | Works (local) | | `deploy` | Works (anonymous deploys, and claimed folds with your developer token) | | `inspect`, `logs`, `db`, `storage` with `--port` | Works against the local dev server | | `inspect`, `logs`, `db`, `storage` with a deploy ID or URL | Coming soon | | `auth as`, `auth reset` | Works (local test identities) | | `claim` | Works | | `auth login`, `auth status`, `auth logout` | Works | | `deploy list`, `deploy archive`, `deploy restore`, `deploy terminate` | Coming soon | | `token`, `domains`, `users` | Coming soon | Commands marked coming soon fail with an error from the server, usually `AOZUMI doesn't support this command yet.` (HTTP 501). ## Create ```sh npx @aozumi/fold new [--template todo] [--no-git] npx @aozumi/fold create # same as new npx @aozumi/fold init [--no-git] # in the current directory ``` Writes the todo starter: `server/index.ts`, `client/index.tsx`, `shared/todo.ts`, `AGENTS.md`, `CLAUDE.md` (which imports `AGENTS.md`), `README.md`, `favicon.svg`, and `.gitignore`. Then it runs `git init` and makes one commit, unless the directory is already inside a git repository or you pass `--no-git`. - `new` without a name asks for one in a terminal and fails in a non-interactive shell. Agents should always pass a name. - `init` and `new ` only work in a directory that is empty or holds only hidden files, README, LICENSE, `AGENTS.md`, and `CLAUDE.md`. Existing `AGENTS.md`, `CLAUDE.md`, and `.gitignore` files get the Fold lines appended. - `todo` is the only template. ## Run locally ```sh npx @aozumi/fold dev [fold-dir] [--port 3000] [--host 127.0.0.1] ``` Serves the fold at `http://localhost:3000` and rebuilds on every file change. It listens on 127.0.0.1; if another program holds the same port on IPv6, `dev` warns and prints the `127.0.0.1` address to use. The `--port` options of `logs`, `db` and `inspect` connect to 127.0.0.1. Keep it running while you work. Data, guest sessions, logs, and uploaded files are in memory and reset on restart. Server env comes from `.env.fold.server`. Outbound `fetch` works here. ```sh npx @aozumi/fold run-many [fold-dir] [--count 20] [--base-port 4000] ``` Starts several local copies of the fold on consecutive ports and prints their URLs. ### Inspect the local server ```sh npx @aozumi/fold logs --port 3000 # ctx.log output and server errors npx @aozumi/fold db list --port 3000 # tables and row counts npx @aozumi/fold db dump --port 3000 # rows npx @aozumi/fold db export --port 3000 --out backup.json npx @aozumi/fold inspect --port 3000 [--query ] [--usage] [--json] npx @aozumi/fold storage list --port 3000 npx @aozumi/fold storage put --port 3000 [--public] [--content-type ] npx @aozumi/fold storage get --port 3000 [--out ] npx @aozumi/fold storage delete --port 3000 ``` Use the port `dev` printed if it is not 3000. ### Local test identities ```sh npx @aozumi/fold auth as alice # dev server treats you as guest "alice" npx @aozumi/fold auth reset ``` You can also add `?fold_guest=` to a local URL. Use separate names or browser profiles to check that users cannot see each other's data. ## Build ```sh npx @aozumi/fold build [fold-dir] [--target claimed|anonymous] [--out .fold/artifacts/app.json] [--json] ``` Builds the deploy artifact locally without publishing. The default target is `claimed`. Run `--target anonymous` before every deploy: it applies the same rules as an anonymous deploy and prints `Build failed` with one line per problem. See [Limits](/fold/limits/#source-rules). ## Deploy ```sh npx @aozumi/fold deploy [fold-dir] [--json] ``` Builds the fold and publishes it to `https://.aozumi.site`. No account is needed. Output without `--json`: ```txt Created anonymous preview. App: https://habit-tracker.aozumi.site Updated: 2026-10-15T09:12:44.000Z Expires: 2026-10-22T09:12:44.000Z Claim: npx @aozumi/fold claim Inspect: npx @aozumi/fold inspect dep_... Limits: source/artifact: 1048576 bytes state: 1048576 bytes requests: 10000 / day mutations: 1000 / day outbound fetch: disabled ``` With `--json`, the output is an object with `deployId`, `url`, `claimUrl`, `claimed`, `status`, `updatedAt`, `expiresAt`, and `limits`. A claimed fold has no `claimUrl`, `claimed` is `true` and `expiresAt` is `null`. - The subdomain comes from `name` in `fold()`. If that name is taken, Fold adds a short random suffix. - The CLI saves the deploy ID and claim token in `.fold/deploy.json`. Running `deploy` again from the same directory updates the same fold, keeps its data, and extends its expiry to 7 days from now. Open pages switch to the new version. - If the saved fold has expired or is gone, `deploy` creates a new one. - If server code uses `fetch`, or `.env.fold.server` has values, the first deploy publishes a placeholder page saying a claim is required. Claiming does not unlock either one yet: outbound fetch and server secrets are coming soon. Remove them and deploy again. - After a claim, `deploy` uses the developer token saved by `claim` or `auth login`, updates the same URL, and prints `Updated owned app.` with `Expires: never`. It also writes `fold.json` with the deploy ID; commit it so a fresh checkout updates the same fold. A claimed fold refuses a deploy whose `.env.fold.server` has values (HTTP 403) until server secrets ship. - Signed in with `auth login` and no saved fold, `deploy` creates a fold that already belongs to your workspace and never expires. - `--public-inspect` is accepted but hosted inspection is coming soon. - Leave `FOLD_TOKEN` unset. CI tokens (`token create`) are coming soon. ## Claim ```sh npx @aozumi/fold claim [fold-dir] npx @aozumi/fold claim --json ``` Claiming moves an anonymous fold into your AOZUMI workspace. A claimed fold keeps its URL and data, never expires, and keeps the anonymous [limits](/fold/limits/) for now. 1. Run `claim` from the folder you deployed from (it reads `.fold/deploy.json`). It opens the claim page in your browser and prints a verification code. 2. On aozumi.dev, sign in with GitHub, check that the code on the page matches your terminal, pick a workspace you can deploy in, and select Claim. 3. The terminal prints `Authenticated.` The CLI saved a developer token for `https://api.aozumi.dev` in `~/.fold/developer-auth.json`. Run `deploy` again to update the claimed fold. `claim --json` only prints `{ claimed, claimUrl, deployId, url }` and does not open anything. The claim link holds a secret token that can take over the app until it is claimed, so share it only with the app's owner. ## Sign in ```sh npx @aozumi/fold auth login # opens aozumi.dev/fold/authorize and prints a code npx @aozumi/fold auth status # who the saved token belongs to npx @aozumi/fold auth logout # forgets the saved token on this computer ``` `auth login` signs this computer in to one workspace without claiming anything. Approve it on the page only if the code matches your terminal. The token stops working if you leave the workspace or lose deploy access there. ## Hosted inspection `inspect`, `logs`, `db`, and `storage` with a deploy ID or app URL are coming soon. Hosted folds answer these with `501`. Test a deployed fold by using it and by calling its endpoints. ## Account commands (coming soon) ```sh npx @aozumi/fold token create --name [--personal] | token list | token revoke npx @aozumi/fold deploy list | deploy archive | deploy restore | deploy terminate --yes npx @aozumi/fold domains add .aozumi.site | domains list | domains status | domains remove npx @aozumi/fold users list | users approve | users deny | users remove ``` These answer HTTP 501 for now. ## Environment variables | Variable | Use | |---|---| | `FOLD_DEBUG=1` | Print full stack traces for CLI errors. | | `FOLD_DEPLOY_API` | Deploy API origin. Defaults to `https://api.aozumi.dev`. Leave it unset. | | `FOLD_TOKEN`, `FOLD_TOKEN_API` | For CI tokens, which are coming soon. Leave unset; `claim` and `auth login` save your token for you. |