@zaip-ai/cli

@zaip-ai/cli

npx @zaip-ai/cli@latest init

Installation profiles:

npx @zaip-ai/cli@latest init
npx @zaip-ai/cli@latest init --profile dev-lite
npx @zaip-ai/cli@latest init --profile lite
npx --yes @zaip-ai/cli@latest init

There are exactly three profiles: full installs application development dependencies and Terraform and is the default for a new project; dev-lite installs development dependencies without Terraform; and lite is for Growth/Ops and skips application development dependencies and Terraform. The chosen profile is saved and reused by later init calls; selecting a smaller profile does not uninstall existing tools. Node/npm remains required even for lite.

npx --yes appears before the package name and suppresses npx's initial package-download prompt. It can be combined with any profile, such as npx --yes @zaip-ai/cli@latest init --profile lite. init --yes, after the package name, is ZAIP's confirmation for --force. Review the dry-run before using --force --yes; the installer creates a backup before replacing files.

Global installation is also supported:

npm install --global @zaip-ai/cli
zaip init

The CLI requires Node.js 22.16.0 or newer. It finds the nearest Git root from the selected directory; outside Git it installs into that directory and reports the fallback. The implementation targets Windows, macOS and Linux using Node.js filesystem APIs; it also implements CI, Git-worktree and paths-with-spaces flows.

Target support is not proof that every operating-system version was executed for a release. Before adopting a candidate, validate installation, permissions and browser/runtime behavior in the target environment. The published CI evidence identifies its own runner; it is not an implicit Windows/macOS/Linux matrix certification.

Installed handbooks and model routing

The installer delivers Portuguese and English handbooks at .agents/README.md and .agents/README-ENG.md, preserving the project's root READMEs even during a forced managed upgrade. Start at .agents/zaip-aios/INDEX.md; the numbered guides are installed under .agents/zaip-aios/guides. Guide 23 explains model routing; guides 12, 20 and 26 cover installation, upgrades and package qualification.

The v4 candidate includes autonomy-v1. New templates use autonomy: { version: 1, preset: balanced } and execution.runtime: codex_native: Codex owns native Sub-Runs, including standalone Tasks, without a separate provider process. Legacy configurations without a runtime retain the manual schema default. Installing or saving a preset does not invoke a provider. Installation profiles are separate from autonomy and assurance.

Autonomy preset	Product executions per Task	Replans
Essential (essential)	4: 1 initial + 3 repairs	1, Sol/high; never automatic Astra
Balanced (balanced)	10: 1 initial + 9 repairs	3: Sol/high, Sol/high, Astra/high
Persistent (persistent, opt-in)	Unlimited	Unlimited

Configure the root autonomy block in .agents/config/project.yaml or save Autonomy preset in Dashboard Project settings. Started Tasks retain their preset and durable consumption; legacy state is not silently migrated. There is no time-based Task abandonment or automatic reduction of acceptance criteria. Persistent may consume credits indefinitely until human cancellation.

Standalone principals prefer direct work with the user's selected model/effort. When delegation is necessary, disclose that ZAIP may select different child models/efforts. Essential permits Astra only as the manually selected standalone principal. In other presets Astra/high may replan from the third plan and execute from the third repair block; it does not replace review or finalization.

Deterministic quotas require the managed dispatch boundary. Native spawn_agent calls made externally by Codex are not intercepted by instructions or later capture. Delivery closure requires a captured eligible executor or an observed direct Task root whose immutable --direct-authorization contract was recorded at start. It still requires applicable review, Evidence and a real immutable Gui decision before canonical Stop; a preference for direct work is not a bypass.

See installed guides 19 (autonomy), 23 (models), and 16 (closure) for exact limits. Missing verification/evidence ends as blocked; a proven technical impediment ends as failed. These changes do not prove financial savings, publication or production readiness, and reach @latest only after release.

Commands and flags

zaip init [directory] [--profile full|dev-lite|lite] [--yes] [--force] [--dry-run] [--verbose] [--project-only]
zaip doctor [directory] [--json]
zaip adapters build [directory] [--force]
zaip adapters check [directory] [--json]
zaip --version
zaip --help

• --yes confirms the destructive phase of --force without an interactive prompt.
• --force backs up the current .agents directory, then reinstalls the official template.
• --dry-run prints the complete plan without writing files or backups.
• --verbose lists technical paths and detected conflicts.
• --profile full|dev-lite|lite selects the installation tools. A new project defaults to full; later runs reuse the saved profile unless explicitly changed. Smaller profiles never uninstall existing dependencies or tools.
• --project-only installs and updates only repository-owned files; it never reads or writes ~/.codex. Without it, initialization removes only deprecated Codex identity aliases declared by the current catalog and idempotently installs the portable ZAIP PreToolUse safety hook. It migrates older ZAIP-owned variants to exactly one canonical block, preserves third-party hooks, and never copies project permissions, project configuration, or agent files to the global Codex profile.

By default, rerunning the command is transactional: any user-owned conflict blocks all writes. Missing files are installed only when the complete plan is conflict-free. Managed agent adapters may be refreshed safely; user-owned adapters are never overwritten without explicit --force.

Updating

With full or dev-lite, init automatically installs missing TypeScript, Vite, Astro, Redis client, BullMQ, Hono, React and React DOM packages in the project. Defaults come from .agents/dashboard/stack-dependencies.json; exact versions in project.yaml → stack.overrides.components take precedence. No approval prompt is needed for dependency installation. A new project receives a private package.json and an npm lockfile.

full additionally prepares the fixed Terraform 1.16.1 release; dev-lite does not install it. lite skips application development dependencies and Terraform while retaining ZAIP's runtime, agents, skills and Dashboard. It is intended for Growth/Ops projects. Node/npm remain necessary to execute the installer.

npx @zaip-ai/cli@latest init --profile lite
npx @zaip-ai/cli@latest init --profile dev-lite
npx @zaip-ai/cli@latest init --profile full

Each command saves stack.overrides.installation_profile in .agents/config/project.yaml for subsequent updates. Use an explicit larger profile to add development or infrastructure tools later. An invalid profile is rejected before installation. --dry-run previews the selected profile without persisting it or downloading tools.

Git and GitHub setup can be completed after installation on every platform. No profile requires Git, a repository, author identity or an initial commit to finish init. Delivery still checks its Git prerequisites before execution.

The successful installation summary includes observed file counts, SQLite and doctor results, and a clickable npm link to the installed version. It ends by asking whether you want help configuring GitHub, or configuring the project when local GitHub configuration is already found. Local configuration does not prove authentication. In a chat, accepting opens the relevant skill, which explains the options and asks for your choices before applying them. GitHub setup is followed by the project setup offer. Completing project setup or deferring an offer ends installation onboarding. The terminal CTA is text only and never waits for an answer.

Terraform is a standalone executable. The full profile reuses a compatible installation or prepares the pinned official Terraform 1.16.1 release locally, verifying its SHA-256 checksum. Provider plugins are downloaded separately by terraform init for the project's .tf configuration. Cloud credentials remain a separate setup step; ZAIP installation never runs terraform apply.

When Terraform is installed locally, npm scripts can find it in node_modules/.bin. You can also invoke it directly: .\node_modules\.bin\terraform.exe version in Windows PowerShell or ./node_modules/.bin/terraform version on macOS/Linux. The installer does not modify the global PATH.

An existing local package is preserved even when its version differs from ZAIP's configuration; the summary reports both versions. When a package is declared but not installed, the project's existing declaration wins. React DOM follows an existing React version when no DOM choice exists. Global packages, another project's dependencies and the npx cache do not satisfy local dependencies.

Installation uses the project's npm, pnpm or Yarn Classic manager, includes development and optional dependencies, and disables lifecycle scripts to avoid executing unrelated project hooks. It does not use --force or bypass peer/engine checks. Conflicting lockfiles, unsupported managers and Yarn 2+/PnP are reported before changing dependency files. If installation fails, package manifests and lockfiles are restored; downloaded modules may remain for a retry. Rerun init after resolving the reported cause. A surviving .local/stack-install.lock after a process crash must be removed only after confirming that its recorded PID is no longer installing.

Node must already be available to execute npm/npx; the installer validates Node 22.16.0+ and preserves it. The complete stack currently needs Node 22.19+ because of transitive dependencies. On older compatible bootstrap runtimes, init downloads the qualified Node 22.23.2 LTS binary from nodejs.org into .local/zaip-node, verifies its official SHA-256, and exposes it to this project's npm scripts through node_modules/.bin. It does not replace the system Node or change global PATH. The Redis npm package is a client library: a Redis server or hosted endpoint remains an application infrastructure choice. SQLite is provided by Node and initialized automatically.

--dry-run displays missing and preserved packages without downloading or changing anything. doctor validates framework files, adapters and Terraform availability for projects with a saved full profile; the installer separately verifies stack packages. Legacy projects without a saved profile do not gain a Terraform requirement from a read-only doctor call.

Run the latest version again. New files are added while local changes remain untouched:

npx @zaip-ai/cli@latest init

Use --force --yes only after reviewing the dry-run. A timestamped backup such as .agents.backup-2026-07-12T153000 is created first. Lifecycle data and unrecognized files are preserved; the operation replaces only files in the signed template plan and can roll back a partial process failure.

Security

The npm artifact contains only the installer, doctor and adapter checks, the public template, documentation, and license. Template hashes are checked before installation. Unsafe paths and symlink traversal are rejected. The template includes the portable lifecycle runtime at .agents/runtime/bin/zaip.mjs and its integrity metadata. It excludes maintainer history, telemetry, customer data, credentials and local environment settings; sanitized configuration examples are included.

Troubleshooting

• Target is not a directory: pass an existing directory.
• --force requires --yes in a non-interactive terminal: add --yes, or rerun interactively.
• Template integrity check failed: reinstall the package from npm and retry.
• Permission errors: run in a writable repository; do not use elevated privileges unnecessarily.

ZAIP-AIOS versus the ZAIP CLI

ZAIP-AIOS is the repository-resident agent workflow and configuration installed under .agents, with minimal Codex and Claude discovery adapters. The ZAIP CLI installs and diagnoses that public template, including its verified portable lifecycle runtime. Installation and local diagnostics do not send repository data to a ZAIP service. Model providers and optional integrations have their own data flows when invoked. The installed guidance references the distributed runtime; the maintainer checkout and its history are not required.

Contributing and license

Run corepack pnpm verify from public-cli before submitting a change. The package metadata uses SEE LICENSE IN LICENSE; the bundled LICENSE carries the proprietary ZAIP-AIOS Commercial License notice. Consult that file for the applicable terms, npm for the published version, and the release evidence for the qualification status.

Repository source v4.5 defines a shared writer claim for serial Tasks, limited parallel worktrees, recoverable isolated checkout closure, a current-release manifest and exact-SHA pre-main CI for critical/builder release delivery. The packaged CLI must pass template/runtime parity and installation qualification before those source rules are treated as an installed version.