Archlast CLI

CLI tool for Archlast development, deployment, and Docker lifecycle management.

Requirements

• Node.js 18+
• Docker Desktop or Docker Engine
• Bun 1.3+

Installation

npm install -g @archlast/cli

On Windows, ensure Bun is on your PATH (the installer adds it, but terminals need a restart):

[Environment]::SetEnvironmentVariable(
  "Path",
  "$env:Path;$env:USERPROFILE\\.bun\\bin",
  "User"
)

Quick start

archlast init
archlast start
archlast status
archlast logs --follow

To watch and auto-deploy functions during development:

archlast dev --path ./archlast --server http://localhost:4000

Commands

• dev - watch archlast/src for changes, regenerate types, and deploy deltas
• deploy - one-time deployment to the server
• build - generate types without deploying
• pull - pull schema/files from the server, or use --docker to pull an image
• init - scaffold the minimal Archlast project structure
• start / stop / restart - manage the Docker container
• status - print container status and health
• logs - stream container logs
• upgrade - pull a new image and restart the container
• config - show resolved Docker config (use --json for JSON)
• generate crud <collection> - scaffold CRUD handlers from schema
• data - snapshot/export/import/restore data (requires ARCHLAST_API_KEY)

Common options

• --path <path> points to your Archlast project folder
• --server <url> sets the API base URL (default: http://localhost:4000)
• --port <port> overrides the container port for start and upgrade
• --config <path> points to archlast.config.js
• --name <name> sets the project name when running init

Configuration

The CLI reads configuration in this order:

1. CLI flags
2. archlast.config.js
3. .env or .env.local
4. defaults

Example archlast.config.js:

export default {
  docker: {
    image: "algochad/archlast-server",
    tag: "latest",
    containerName: "archlast-server",
    restartOnDeploy: true,
  },
  server: { port: 4000 },
  paths: {
    config: ".archlast/config",
    deploy: ".archlast-deploy",
  },
  cors: { origins: ["http://localhost:3000"] },
  env: {
    ARCHLAST_DASHBOARD_PORT: "4001",
    ARCHLAST_STORE_PORT: "7001",
  },
};

Environment variables starting with ARCHLAST_, S3_, AWS_, and STORAGE_ are forwarded into the container.

If containerName or volumeName is not set, the CLI generates unique names per project to keep data isolated.

The CLI stores per-project metadata in .archlast/project.json and persists the selected port when it has to pick a new one.

When restartOnDeploy is enabled, archlast dev and archlast deploy restart the Docker container after a successful upload.

Dev and deploy flow

The server receives deployments at POST /_archlast/deploy with payload:

{
  functions: Array<{
    name: string;
    type: "query" | "mutation" | "action";
    filePath: string;
    code: string;
  }>;
  schema: { filePath: string; code: string } | null;
  timestamp: number;
}

Data management

Use the data command group to snapshot, export, import, and restore data. Set ARCHLAST_API_KEY in your environment for authentication.

Examples:

archlast data snapshot --name "pre-migration"
archlast data export ./backup.zip
archlast data import ./backup.zip --strategy merge
archlast data restore snapshot-2026-01-01.zip

Publishing (maintainers)

See docs/npm-publishing.md for the release workflow and manual publish steps.