Zalos CLI

zl is the globally installed, API-only product CLI. Use it from any repository. It emits JSON on stdout, structured errors on stderr, and nonzero exit codes on failure. zalos-db separately owns query-only database and stdio MCP access through AWS Identity Center. mesh remains the repository-local operator and runtime CLI.

Install

Requires Node.js 22 or newer. The product CLI is public on npm and does not require GitHub CLI or GitHub Packages access.

npm install --global @zalosai/[email protected]

Installing the CLI does not grant access.

Agent skills

The package includes a production-operations skill for Codex and Claude. It describes region selection, browser login, team switching, preview-first changes, workflow publishing, Team Files, Pages, and Motion work without embedding credentials.

zl skills list
zl skills read zl-ops
zl skills install zl-ops --target codex
# Or:
zl skills install zl-ops --target claude

Codex installs to $CODEX_HOME/skills when CODEX_HOME is set, otherwise ~/.codex/skills; Claude installs to ~/.claude/skills. Use --directory <path> to install beneath a custom skills root. Installation leaves an identical existing skill unchanged and refuses to replace local edits unless --force is explicitly supplied. These commands work locally and do not need authentication or an environment selection.

First run

zl --environment staging auth login
# Equivalent regional choices:
zl --environment us-prod auth login
zl --environment eu-prod auth login

auth login opens the existing browser sign-in and stores the scoped human session. If the browser cannot reach the CLI's local listener, choose Use a code in the browser and enter the code printed by the CLI, then confirm the team. For a CLI running on another machine or in a container, run zl --environment <name> auth login --device. Open the verification page printed by the CLI on a browser machine, enter its six-digit code, and confirm the team. The CLI waits up to five minutes and receives the token encrypted to the CLI session key. It never changes access-group membership. Database access remains an optional, separately distributed developer capability:

npm login --scope=@zalos-io --auth-type=legacy --registry=https://npm.pkg.github.com
npm install --global @zalos-io/[email protected]
zalos-db login --environment staging

Every remote command requires --environment staging|us-prod|eu-prod or an explicit ZL_ENVIRONMENT. The origins are respectively dev.app.zalos.ai, app.zalos.ai, and app.eu.zalos.ai. There is no regional fallback. --api-url accepts an explicit loopback origin for local development only; ZL_API_URL is not an override.

Human browser tokens are team-scoped and expire after seven days. team list shows the active teams and immutable public IDs available to the signed-in user, and team switch <team-ref> changes the selected profile to one of those teams without another browser login. The switch preserves the session's original expiry and token scopes. Profiles live at $XDG_CONFIG_HOME/zalos/credentials.json (default ~/.config/zalos/credentials.json), with directory mode 0700 and file mode 0600. Symbolic links are rejected. There is no Keychain integration. Use --profile for multiple teams/environments. Legacy profiles must be renewed with auth login. auth logout attempts server revocation and clears the local profile even if the server cannot be reached, reporting that failure.

AWS portal sessions and permission-set credentials have independent expiry policies. When AWS access expires, rerun zalos-db login --environment <name>; this does not renew your Mesh token. Database reader groups are zalos-db-staging-readers, zalos-db-us-prod-readers, and zalos-db-eu-prod-readers.

Data Tables

Define columns, types, write owners, and an optional text business key in a local JSON schema. Initial rows may be a JSON array or .jsonl file.

zl data-table validate --schema /tmp/table.json --rows /tmp/rows.jsonl
zl --environment staging data-table create --schema /tmp/table.json --rows /tmp/rows.jsonl
# Review the preview, then run its applyCommand unchanged.
zl --environment staging data-table list
zl --environment staging data-table view <table-id>
zl --environment staging data-table grant-writer <table-id> <workflow-id> --apply
zl --environment staging data-table revoke-writer <table-id> <workflow-id> --apply

Creation requires team owner access. The preview provides a stable operation key, checksum, and destination origin for apply. Import accepts at most 1,000 rows and a 1 MB request. Workflow writer grants are separate and preview by default.

Product operations

export ZL_ENVIRONMENT=staging
zl workflow list --fields id,name
zl workflow list --all-teams --limit 100
zl workflow view <id>
zl workflow export --all-teams --pretty --output /tmp/mesh-staging-workflows.json
zl workflow publish <workflow-id> --apply
zl execution list --limit 1
zl execution view <id>
zl execution summary <id>
zl execution artifact download <artifact-id> --output /tmp/artifact
zl execution replay export <execution-id> --output .zalosai/replays/<execution-id>
zl page list --fields id,title,updatedAt
zl page export <page-id> --output /tmp/month-end-close.md
zl page create --input /tmp/month-end-close.md --apply
zl page update <page-id> --input /tmp/month-end-close.md --apply
zl workflow run <id> --dry-run
zl workflow run <id>
zl template list
zl credential list
zl file list
zl team list
zl team switch <team-ref>
zl team list --all-teams
zl file tree --team-id <team-ref>
zl file find <query> --team-id <team-ref>
zl file inspect <file-id> --team-id <team-ref>
zl file download <file-id> --team-id <team-ref> --output /tmp/file
zl file snapshot --team-id <team-ref> --output /tmp/team-files.json
zl file seed --source-team-id <team-ref> --source-path /Fixtures --target-path /Rehearsal
zl file seed --source-team-id <team-ref> --source-scope generated-outputs --source-path /__mesh/outputs/<execution-id> --target-path /Priors
zl file seed --source-team-id <team-ref> --source-path /Fixtures --target-path /Rehearsal --apply --expected-checksum <sha256>

Workflow import/update/publish require --apply; without it they validate and print a preview. workflow run executes unless --dry-run is supplied. Product authorization comes from the signed-in human's team membership, role, and token scopes. Credential reads return metadata only. No product command loads database credentials.

For protected workflows, workflow update --apply saves a draft. Its response reports whether runs use that version and names the live version when they do not. Use workflow publish <workflow-id> --apply to promote the current draft. workflow export keeps stdout as reusable workflow JSON and writes a structured stderr warning when the exported draft differs from the version used by runs.

workflow list --all-teams and workflow export --all-teams read every workflow in the selected regional database. They require an internal Zalos human CLI token with workflows:read; external users and automation tokens are rejected. workflow export --all remains scoped to the selected profile's team. Run cross-team reads separately for us-prod and eu-prod when both production regions are needed. Cross-team exports include each workflow's server checksum so the file can be used with workflow update, including a content-derived baseline for legacy rows that predate stored checksums.

All human users can discover their active memberships with team list and select one with team switch <team-ref>. Prefer the listed immutable publicId, such as tm_4ERk9QxW; legacy internal UUIDs remain accepted. Treat public IDs as opaque strings— their suffix length is not an API contract, and they are not database foreign keys. Mutating commands then use that selected team context. Internal human developers can also discover regional team IDs with team list --all-teams and use an explicit ID with file tree, find, inspect, download, or snapshot. Downloads request a short-lived URL through the authenticated API and write to a new private file; they do not require direct S3 access. File moves remain scoped to the selected team profile. Execution artifact downloads use the same private-file and no-overwrite guarantees. Select the artifact's team before downloading; the immutable artifact API enforces that team boundary. execution replay export packages the selected team's ready immutable input and output artifacts with their recorded SHA-256 hashes. It verifies every downloaded byte, writes a new private local directory, and never prints signed URLs. Run the bundle locally with uv run zalosai run --replay-bundle <directory> from Agent Studio; this does not use database, SSM, or direct S3 credentials. page export writes a Markdown process document with a non-rendered revision marker. Edit the Markdown, then use page update --apply; it refuses an update when the Page changed after export. page create and page update both preview by default and preserve common Tiptap process-document structures such as headings, lists, checklists, quotes, code blocks, links, and emphasis. Exports reject unsupported inline content, combined marks, and nested or multi-block list items so a Markdown edit cannot silently discard Page content. file seed copies a source file or subtree into the selected team with server-side storage copies. Use --source-scope generated-outputs to carry prior-period agent outputs into normal Team Files; the default source scope is files. It previews the complete path mapping and checksum by default. Apply the reviewed checksum with --apply --expected-checksum <sha256>; changed inventories are rejected. The command preserves paths below the selected source, creates independent destination files, resumes files already copied by the same plan, and blocks on unrelated destination collisions. Switch to the rehearsal team before applying the plan.

printf 'SELECT current_database()' | zalos-db query --environment staging
zalos-db mcp --environment eu-prod

Database queries retain the 500-row ceiling, read-only transaction, five-second statement timeout, and rollback. Each MCP process is pinned to one environment.

Automation

Use scoped bot tokens injected into ZL_API_TOKEN and set ZL_ENVIRONMENT explicitly. Automation never reads or writes human profiles. Do not save bot tokens with browser login or reuse human credentials for unattended work. Existing legacy bot tokens retain compatibility during deliberate owner-managed rotation; new tokens use explicit scopes. Server-provisioned team bots retain their existing runtime API access through a reserved automation:internal scope. Only internal team provisioning can issue it; browser CLI login and public token creation cannot request it. Team/resource authorization still applies.

Manage Motion

Resolve IDs before creating or updating tasks:

zl project list --fields id,name
zl state list --project-id <project-id> --fields id,name,type
zl task list --project-id <project-id> --fields id,title,stateId

Inspect accepted fields, preview a mutation, and then apply it:

zl schema task

zl task create --project-id <project-id> \
  --json '{"title":"Fix login bug","priority":"high"}' \
  --dry-run

zl task create --project-id <project-id> \
  --json '{"title":"Fix login bug","priority":"high"}'

zl task view, create, update, and move include a canonical url in their response. Move a task without manually reconstructing its project state or link:

zl task move <task-id> --project-id <target-project-id> --dry-run
zl task move <task-id> --project-id <target-project-id>

API tokens

Use browser authorization to provision a least-privilege token for any team where the signed-in user has an active membership. The browser selects the team and authorizes automatically when its session is already active. This uses the product API; it does not require database access, a tunnel, or an RDS certificate.

zl --environment us-prod api-token create \
  --label "CI investigation" \
  --scopes workflows:read,executions:read \
  --expires-at 2026-10-01T00:00:00Z

Creation returns the plaintext token once. Store it in the approved secret manager immediately; the CLI does not persist it as a human profile.

Resolve an assignee from the current team, then upload a screenshot as an image attachment:

zl member list --fields id,name,email
zl task attachment upload <task-id> ./workflow-unpublished-changes.png

Task attachments support png, jpeg, gif, webp, avif, and svg images (up to 10 MB). zl project list excludes archived projects by default; pass --include-archived for historical lookup.

Run zl --help or zl <resource> --help for the complete command surface. The available resources are workflow, execution, template, credential, file, team, page, task, project, state, label, cycle, and member; task comments and attachments are managed under zl task.

Automation contract

• Successful output is JSON on stdout.
• Errors are JSON on stderr and exit with status 1.
• --fields id,title,... limits list and view payloads.
• --dry-run previews supported writes without making an HTTP request.
• zl schema [resource] is local and does not require authentication.
• ZL_API_URL takes precedence over a profile URL, which takes precedence over the production default.
• ZL_API_TOKEN takes precedence over the token in the selected profile.

Never print tokens in logs or commit ~/.config/zalos/credentials.json.