Zenifra CLI

The zenifra-cli is Zenifra's official command-line interface. It lets you operate the platform from terminals, scripts, and pipelines without relying on the web console for repetitive tasks.

Use the CLI to authenticate, switch profiles, inspect plan catalogs, create projects, list resources, trigger deploys, follow builds, read logs, change environment variables, and inspect metrics.

Installation

Install the package from npm:

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

Each command has specific help with usage examples and expected output:

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

Use this help before automating a flow in CI/CD to confirm the supported flags.

Authentication

Use user login when you are working interactively and need to navigate between organizations:

zenifra auth login
zenifra orgs
zenifra org set

This mode is intended for local use because a user account can belong to multiple organizations.

API key for automation

Use an organization API key for 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

You can also save the key in the active local profile:

zenifra auth api-key --key znf_your_key

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

Profiles and environments

The CLI uses local profiles to separate credentials, descriptions, and API base URLs:

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

Environment variables can override the profile configuration for a single execution:

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

Use ZENIFRA_CONFIG_DIR in tests and temporary validation when you do not want to alter the real machine session.

Inspect plans

Before creating a project, inspect the public catalogs for HTTP, database, and storage plans:

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

zenifra plans does not require authentication. Human output shows category tables, while --json returns structured data for scripts.

Create projects

To create a project with the interactive wizard, run:

zenifra create project

The wizard asks for the required fields, shows examples, and makes clear which values must be provided. The CLI does not assume default values for plan or payment mode; choose those values from the catalog returned by zenifra plans.

For automation, use a configuration file:

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

The command also accepts configuration for HTTP projects with GitHub or OCI image sources, plus PostgreSQL and MariaDB projects.

Operate projects

After the project exists, use the CLI to inspect status, URL, logs, metrics, environment variables, and instances:

zenifra projects --type http --page 1 --limit 15
zenifra project info --project <project-id>
zenifra project url --project <project-id>
zenifra project logs --project <project-id> --instance <instance-id>
zenifra project metrics --project <project-id> --instance <instance-id>
zenifra project envs --project <project-id>
zenifra project instances --project <project-id>

zenifra projects is paginated by default with 15 projects per page. Use --page <n> to navigate and --limit <n> to adjust page size when automating list operations.

For environment variables:

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

Variable values are masked by default, including in JSON output. Use flags to show full values only when necessary and safe.

Deploys and builds

Trigger a manual deploy from the configured branch:

zenifra deploy --project <project-id> --branch main

List builds and deploys:

zenifra builds --project <project-id>
zenifra deployments --project <project-id>

Watch a build until it finishes:

zenifra deploy watch --project <project-id> --build <build-id>

This flow is useful for pipelines that need to wait for the build result before running external validation.

Security

Store ZENIFRA_API_KEY in CI provider secrets.
Prefer environment variables in ephemeral runners, without writing a local session.
Configure IP allowlists when automation has a fixed origin.
Grant only the permissions required by the job.
Rotate and revoke old keys.
Avoid printing full sensitive variable values in CI logs.