CLI

Every npx @aozumi/fold command, and whether it works today.

Run commands with npx @aozumi/fold <command> (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

Commands marked coming soon fail with an error from the server, usually This needs a signed-in deploy, which AOZUMI doesn't support yet. (HTTP 501), or ask you to sign in first.

Create

npx @aozumi/fold new <name> [--template todo] [--no-git]
npx @aozumi/fold create <name>          # 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 <existing-dir> 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

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.

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

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 <name>] [--usage] [--json]
npx @aozumi/fold storage list --port 3000
npx @aozumi/fold storage put <file> --port 3000 [--public] [--content-type <type>]
npx @aozumi/fold storage get <key> --port 3000 [--out <file>]
npx @aozumi/fold storage delete <key> --port 3000

Use the port dev printed if it is not 3000.

Local test identities

npx @aozumi/fold auth as alice    # dev server treats you as guest "alice"
npx @aozumi/fold auth reset

You can also add ?fold_guest=<name> to a local URL. Use separate names or browser profiles to check that users cannot see each other's data.

Build

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.

Deploy

npx @aozumi/fold deploy [fold-dir] [--json]

Builds the fold and publishes it to https://<name>.aozumi.site. No account is needed.

Output without --json:

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.

• 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. Remove those and deploy again.
• --public-inspect is accepted but hosted inspection is coming soon.
• Do not set FOLD_TOKEN. Signed-in deploys are coming soon, and with it set, deploy fails with HTTP 501.

Claim

npx @aozumi/fold claim --json

Prints { claimed, claimUrl, deployId, url } from .fold/deploy.json. The claim link holds a secret token that can replace the app, so share it only with the app's owner.

Claiming a fold into an AOZUMI account is coming soon. Today the claim page shows the app URL and its expiry. claim without --json tries to start a sign-in and fails.

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)

npx @aozumi/fold auth login | auth status | auth logout
npx @aozumi/fold token create --name <name> [--personal] | token list | token revoke <id>
npx @aozumi/fold deploy list | deploy archive <id> | deploy restore <id> | deploy terminate <id> --yes
npx @aozumi/fold domains add <name>.aozumi.site | domains list | domains status <host> | domains remove <host>
npx @aozumi/fold users list | users approve <id-or-email> | users deny <id-or-email> | users remove <id-or-email>

These need a signed-in AOZUMI account, which Fold does not support yet.

Environment variables