Zenifra CLI

zenifra-cli is the official Zenifra command-line interface (current version: 0.6.1). It lets you operate the platform from a terminal, scripts, and pipelines without relying on the web console for repetitive tasks.

Installation

npm install -g @zenifra/cli
zenifra --help

Every command has its own help with flags, examples, and expected output:

zenifra help create project
zenifra plans --help
zenifra deploy watch --help

If you run an incomplete command such as zenifra deploy or zenifra builds, the CLI opens that command's help. All listing commands accept --json, which is useful in scripts.

Required permissions

owner has full access. assistant, member, and API Keys need the matching grants.

Using it with coding agents

Coding agents with terminal access can use the CLI directly. For Codex, the official Zenifra plugin guides the agent to use the same CLI commands and profiles, with the credentials and permissions you configured.

• Zenifra plugin for Codex

To only query data from an AI client, Zenifra MCP provides read-only OAuth access. Use the CLI for terminal operations and MCP for queries inside the AI client.

Authentication and profiles

User login

Best for interactive use, when you move between organizations:

zenifra auth login
zenifra orgs
zenifra org set
zenifra whoami

zenifra whoami shows the active profile, the API, and the selected organization, without exposing credentials.

Browser login (OAuth)

Opens the Console so you can sign in, complete the security check, and approve CLI access:

zenifra auth login --oauth
zenifra auth login --oauth --read-only
zenifra auth login --oauth --no-browser

• --read-only requests read-only access; your organization permissions still apply.
• --no-browser prints the address so you can open it manually in a browser on the same machine.
• --read-only and --no-browser require --oauth.
• The login waits up to three minutes; press Ctrl+C to cancel. Tokens are kept in the private local profile and renewed automatically.

Without --oauth, auth login uses email, password, and verification.

API key for automation

Use an organization API key in scripts, runners, and pipelines:

export ZENIFRA_API_KEY=znf_your_key
zenifra projects --type http --page 1 --limit 15
zenifra deploy --project <project-id> --branch main

Or save the key in the active profile:

zenifra auth api-key --key znf_your_key

API keys already carry their linked organization, so projects, deploy, builds, and deployments do not require org set. Personal commands such as orgs and org set require zenifra auth login.

Sign out and revoke

zenifra auth logout            # removes local authentication only
zenifra auth logout --revoke   # also revokes the profile's connection

--revoke requires a profile authenticated by login and does not revoke API keys.

Profiles and environments

Local profiles separate credentials, description, and API base:

zenifra profile list
zenifra profile add --name prod --description Production --api-base https://api.zenifra.com/v1 --mode api-key --key znf_your_key
zenifra profile use prod
zenifra profile show
zenifra profile edit prod --description "Main production"
zenifra profile remove prod

auth login --profile <name> and auth api-key --profile <name> create or update another profile and make it active. Do not reuse a token against another API: create another profile.

Environment variables override the profile only for the current run:

ZENIFRA_API_URL=https://api.zenifra.com/v1 zenifra projects --type http
ZENIFRA_CONFIG_DIR=/tmp/zenifra-cli zenifra profile list

ZENIFRA_API_KEY takes precedence over the profile credential. Use ZENIFRA_CONFIG_DIR in tests to avoid changing your real session.

Organizations

zenifra orgs
zenifra org set
zenifra org set --org <organization-id>

Inspect plans

Before creating a project, compare the public catalogs. The command does not require authentication:

zenifra plans
zenifra plans --type http
zenifra plans --type database
zenifra plans --type valkey
zenifra plans --type storage --json
zenifra plans --type job

Output shows tables per category; for HTTP plans it includes the available capabilities (logs, metrics, health check, auto-scaling, custom subdomain, and network access). Use --json for scripts.

Create projects

With no arguments, the CLI opens an interactive wizard that asks for each field and shows examples and related documentation:

zenifra create project

The wizard covers HTTP projects (image or GitHub), PostgreSQL, MariaDB, Valkey (Key‑Value, Cache, and Queues), and scheduled Jobs. ClickHouse and HTTP projects with a connected Git source use the non-interactive mode with --config.

For automation, pass a configuration file:

zenifra create project \
  --name app-api \
  --plan free \
  --payment-mode hourly \
  --config @examples/http-project.json

The CLI does not assume --plan or --payment-mode (except Jobs, which use per_minute); choose them from zenifra plans.

--config accepts these type_project values:

payment_mode values: hourly, monthly, yearly, and per_minute (Jobs only). For HTTP projects, set config.exposure:

• public: creates a public route and domain.
• private: creates the project without a public domain, suited to automations and internal routines.

Ready-made configuration examples are in the examples/ folder of the CLI repository (http-project.json, http-git-project.json, postgresql-project.json, clickhouse-project.json, job-project.json, and more).

Deploy from an image

zenifra project image set --project <project-id> --image ghcr.io/zenifra/app:1.2.0

Always prefer a fixed version tag over latest.

Deploy from Git

Projects can use a Git source from a supported provider (GitHub or Forgejo). An organization owner creates the connection in the Console; the CLI lists and uses existing connections and never asks for or shows provider credentials.

Check providers, runtimes, and connections, resolve the repository by path, and list branches:

zenifra git providers
zenifra git runtimes
zenifra git connections
zenifra git repositories resolve --connection <connection-id> --path team/application
zenifra git branches --connection <connection-id> --repository <repository-id>

The ID returned by resolve belongs to that connection. Use the IDs in config.source and config.build when creating the project (see examples/http-git-project.json):

zenifra create project --name api-web --plan basic --payment-mode hourly --config @examples/http-git-project.json

Inspect and change the project's source and deploy mode:

zenifra project source --project <project-id>
zenifra project source branches --project <project-id>
zenifra project source deploy-settings set --project <project-id> --mode branch
zenifra project source deploy-settings set --project <project-id> --mode tag --tag-pattern "v*"
zenifra project source deploy-settings set --project <project-id> --mode release --tag-pattern "v*" --include-prereleases true

Modes are manual, branch, tag, and release. tag and release require --tag-pattern (* and ? wildcards); --include-prereleases only applies to release and defaults to false. Avoid changing the source at the same time from the Console or another client.

Projects with a legacy GitHub configuration keep using zenifra project github and zenifra project github deploy-settings set, with the same modes.

Trigger and follow builds

zenifra deploy --project <project-id> --branch main
zenifra deploy watch --project <project-id> --build <build-id>
zenifra builds --project <project-id>
zenifra builds logs --project <project-id> --build <build-id> --follow
zenifra deployments --project <project-id>

zenifra deploy triggers the Git build/deploy and returns a build_id. deploy watch follows the status and prints incremental logs until the final state, which is handy in pipelines. Log differences:

• zenifra project logs: the running application
• zenifra builds logs: the Git build pipeline
• zenifra deploy watch: status + logs of a specific build

Configure projects

zenifra project info --project <project-id>
zenifra project url --project <project-id>
zenifra project stop --project <project-id>
zenifra project resume --project <project-id>
zenifra project delete --project <project-id> --yes

Environment variables (values masked by default, including in --json):

zenifra project envs --project <project-id>
zenifra project env add --project <project-id> --name NODE_ENV --value production
zenifra project env update --project <project-id> --name NODE_ENV --value staging
zenifra project env remove --project <project-id> --name NODE_ENV

Use --show-values on envs only when necessary and safe.

Exposure, instances, and auto-scaling (HTTP projects):

zenifra project exposure set --project <project-id> --exposure private
zenifra project instances set --project <project-id> --count 3
zenifra project autoscaling set --project <project-id> --min 2 --max 8 --cpu 70 --memory 80
zenifra project autoscaling disable --project <project-id>

private removes the public route, the Zenifra subdomain, and custom domains; public restores them. With auto-scaling enabled, adjust the range through the autoscaling command: manual instance changes are blocked until you disable it.

Health check:

zenifra project healthcheck get --project <project-id>
zenifra project healthcheck set --project <project-id> --path /health
zenifra project healthcheck disable --project <project-id>

Observe projects

zenifra projects --type http --page 1 --limit 15
zenifra project logs --project <project-id> --instance <instance-id>
zenifra project metrics --project <project-id> --instance <instance-id>
zenifra project metrics capabilities --project <project-id>
zenifra project network --project <project-id> --view summary
zenifra project healthcheck failures --project <project-id>
zenifra project autoscaling events --project <project-id> --direction scale_up
zenifra project billing usage --project <project-id> --from 2026-06-01T00:00:00Z --limit 20

• zenifra projects paginates at 15 items per page; adjust with --page and --limit.
• project metrics capabilities reports the access level and available metric groups before you fetch a snapshot; missing values appear as indisponivel.
• project network --view accepts summary, status-codes, routes, user-agents, request-events, and source-ips.
• autoscaling events accepts --direction scale_up|scale_down, --from, and --to; billing usage accepts --from and --to in ISO format.

Scheduled jobs

Check plans with zenifra plans --type job and create the Job with a ready-made image and a five-field cron in UTC. Jobs are billed per whole minute and do not use a Git source, exposure, port, or instances:

zenifra create project --name nightly-report --plan job-basic --payment-mode per_minute --config @examples/job-project.json

Follow the runs:

zenifra project runs --project <project-id> --page 1 --limit 20
zenifra project runs logs --project <project-id> --run <run-id>
zenifra project runs cancel --project <project-id> --run <run-id>

runs cancel cancels only the selected run and waits up to 30 seconds for a safe finish; the cron keeps scheduling new runs. Use zenifra project stop to pause the project and stop future runs.

Data services

PostgreSQL, MariaDB, and ClickHouse

zenifra create project --name app-db --plan db-basic --payment-mode monthly --config @examples/postgresql-project.json
zenifra create project --name app-db --plan db-basic --payment-mode monthly --config @examples/mariadb-project.json
zenifra create project --name events --plan analytics-starter --payment-mode hourly --config @examples/clickhouse-project.json

The wizard and examples do not ask for a username, password, or database name.

Valkey

Check zenifra plans --type valkey first. The plan identifies the profile: db-* for Key‑Value, cache-* for Cache, and queue-* for Queues. The supported version in this example is 9.1.1.

Key‑Value is persistent and uses storage:

{
  "type_project": "valkey",
  "profile": "key_value",
  "version": "9.1.1",
  "storage": {
    "persistent": true,
    "capacity": 5
  }
}

zenifra create project --name sessions --plan db-basic --payment-mode monthly --config @key-value.json

Cache is disposable and sends no storage:

{
  "type_project": "valkey",
  "profile": "cache",
  "version": "9.1.1"
}

zenifra create project --name product-cache --plan cache-basic --payment-mode monthly --config @cache.json

Queues use persistent storage for Streams and consumer groups:

{
  "type_project": "valkey",
  "profile": "queue",
  "version": "9.1.1",
  "storage": {
    "persistent": true,
    "capacity": 5
  }
}

zenifra create project --name email-workers --plan queue-basic --payment-mode hourly --config @queue.json

Do not provide an image, runtime, port, instance count, or IP rules. Valkey is publicly reachable over IPv4 and protected by TLS and authentication; see the Valkey overview, the Key‑Value Database, Cache, Queues, and the REST reference.

To operate the service:

zenifra projects --type valkey
zenifra valkey status --project <project-id>
zenifra valkey connection --project <project-id>
zenifra valkey credentials rotate --project <project-id> --wait
zenifra valkey credentials status --project <project-id> --operation <operation-id>

The connection you query is masked; the full credential appears only at creation or after a completed rotation. To save it to a private file without printing it:

zenifra valkey credentials rotate --project <project-id> --wait --connection-file /private/path/connection.txt

Security

• Store ZENIFRA_API_KEY in your CI provider's secrets.
• Prefer an environment variable on ephemeral runners, without saving a local session.
• Configure an IP allowlist when the automation has a fixed origin.
• Grant only the permissions the job needs.
• Rotate and revoke old keys.
• Avoid printing full values of sensitive variables in CI logs.

Next steps

• Organization API Keys
• GitHub deployments
• Deploy and Automation CLI
• Observability
• Production checklist