Deploy with the CLI

Install

The CLI is the npm package @aozumi/aozumi. It needs Node.js 18 or later. This guide describes version 0.1.5; check yours with npm ls -g @aozumi/aozumi.

npm i -g @aozumi/aozumi
aozumi --help

The package is open source under Apache-2.0 and published with npm provenance.

Sign in

aozumi login

1. The CLI shows a login codeIt also opens the approval page in your browser. Use --no-browser to open the printed link yourself.
2. You approve in the browserCheck that the code matches your terminal. The page shows when the request was made and what access it grants, and has a Deny button.
3. The CLI saves a keyThe key works for CLI deploys in the workspace you approved. It is saved to ~/.config/aozumi/credentials.json (or under $XDG_CONFIG_HOME) with owner-only file permissions where the system supports them.

The key appears under Profile → Agents in Aozumi. To sign out and revoke it:

aozumi logout

If Aozumi cannot be reached, logout still removes the local file and tells you to revoke the key under Profile → Agents.

Deploy a site

Run deploy from the project folder with a site name. The name identifies the site in your workspace; deploying again with the same name publishes a new release of the same site.

cd my-project
aozumi deploy my-site

The CLI reports the detected stack, packages the files, uploads and verifies them, then prints the URL on its own line, so scripts can capture it:

URL=$(aozumi deploy my-site --team)
echo "Deployed to $URL"

Static sites can hold up to 5,000 files and 256 MB per release. Single-page apps built with Vite get history fallback to index.html automatically.

How the output is found

Without --dir, the CLI looks in this order:

1. A built folder with an index.html: dist, build, out or public. If more than one exists, it stops and asks you to choose one with --dir.
2. No built folder but a build script in package.json: it asks before running the build with your package manager (npm, pnpm, yarn or bun, from packageManager or the lockfile). --yes approves it without asking.
3. An index.html in the folder itself and no package.json: a hand-written site. From 0.1.5 the CLI publishes it with no --dir needed. Only web files are published; dotfiles, node_modules, keys, and source and config files are skipped, and the CLI lists what it skipped.

# publish a specific folder
aozumi deploy my-site --dir=dist

# publish the current folder as a plain HTML site
aozumi deploy my-site --dir=.

The stack is detected from package.json and the files present. Astro can build either static pages or a server, so the CLI asks you to pass --stack=astro-static for a static export.

Link access

Each site has one of three link access settings:

--public

Anyone with the link can open it.

--team

People in your Aozumi workspace.

--private

Only people you invite.

The first deploy of a new site asks once in an interactive terminal; the default answer is private. Without a terminal, such as in CI, a new site is private unless you pass a flag. Existing sites keep their setting unless you pass a flag, and the CLI prints the current setting after each deploy. Making a site public or team-visible needs a workspace role that can manage apps.

Server apps

For apps that need a running server, the CLI can upload a prebuilt server artifact instead of static files: --stack=node, --stack=nextjs (from .next/standalone) or --stack=go. The default start commands are npm start, node server.js and ./server; override with --run.

aozumi deploy my-api --stack=node --run="node dist/server.js" --private

If an upload is interrupted, the CLI prints a release ID; rerun with --release=<id> to resume that exact artifact.

CI and tokens

Set AOZUMI_TOKEN to use a key without a saved login: the token value that aozumi login saved in credentials.json. It takes precedence over the saved login. In CI, always pass a link access flag and --yes if a build may be needed.

- run: npx @aozumi/aozumi deploy my-site --team --yes
  env:
    AOZUMI_TOKEN: ${{ secrets.AOZUMI_TOKEN }}

The CLI never asks for cloud provider credentials, and you should never give it any. Keep AOZUMI_TOKEN in your CI secret store.

Command reference

Troubleshooting

“Run aozumi login to connect your account, or set AOZUMI_TOKEN.”

No saved login was found. Run aozumi login, or set AOZUMI_TOKEN in CI.

“Found multiple static outputs”

More than one of dist, build, out and public contains an index.html. Pick one with --dir.

“A build is required … pass --yes”

There is no built output and the CLI cannot ask, because it is not running in a terminal. Build first, or pass --yes.

“This AOZUMI site is already configured for a different artifact stack.”

A site keeps the kind of artifact it was created with. Choose another site name.

Questions

How do I deploy a static site with Aozumi?

Run npm i -g @aozumi/aozumi, then aozumi login, then aozumi deploy my-site in the project folder. The CLI publishes an existing dist, build, out or public folder that contains index.html. If there is none and package.json has a build script, it asks before running the build locally. From 0.1.5, a folder with index.html and no package.json is published without --dir; only web files are included.

Does the CLI upload my source code?

No. The CLI builds on your machine and uploads only the built output: static files, or a prebuilt server artifact. Aozumi never receives your Git repository from the CLI and does not run your build.

How do I use the Aozumi CLI in CI?

Set the AOZUMI_TOKEN environment variable to the key saved by aozumi login, and pass --yes if the CI job should run the build without a prompt. Pass --public, --team or --private to set link access explicitly, because CI has no terminal to ask in.

Can I use a CLI key with the MCP endpoint?

No. Keys created by aozumi login are limited to CLI deploys in the workspace you approved, and the MCP endpoint refuses them. Create a separate agent key under Profile → Agents for MCP clients.