Deploy and Automation CLI

Zenifra's CLI lets you list projects, create resources, and trigger deployments from the terminal, scripts, and pipelines.

Required permissions

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

This page summarizes deploy and automation commands. For the full tool reference, see Zenifra CLI.

Use the CLI when you want to operate Zenifra without opening the console: create a project, inspect plan catalogs, list resources, trigger deploys, and follow builds.

Quick start

npm install -g @zenifra/cli
zenifra auth login
zenifra whoami
zenifra projects --type http --page 1 --limit 15
zenifra create project
zenifra deploy --project <project-id> --branch main
zenifra deploy watch --project <project-id> --build <build-id>

For Git projects, zenifra deploy triggers the build and returns build_id. Then zenifra deploy watch follows status and incremental logs until completion.

To see all available commands:

zenifra --help
zenifra help create project

Incomplete commands such as zenifra deploy, zenifra deploy watch, and zenifra builds open command-specific help.

Authentication

User login

Use user login to navigate between organizations:

zenifra auth login
zenifra orgs
zenifra org set

zenifra auth login uses the traditional email, password, and verification flow. This mode is intended for interactive terminal use.

OAuth login

Use OAuth when you want to authenticate in a browser:

zenifra auth login --oauth
zenifra auth login --oauth --no-browser

The first command opens a browser automatically. With --no-browser, the CLI displays the address to open manually. In both cases, the browser and CLI must be on the same machine: the OAuth return completes through a local loopback callback. If that machine has no graphical session or the local callback cannot be completed, use an organization API key in the execution environment.

API key for automation

For CI/CD and server-side jobs, create an organization API key and use:

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 local session:

zenifra auth api-key --key znf_your_key

API keys already carry their linked organization. Automation commands therefore do not require org set.

Create a project from the terminal

Run zenifra create project without flags when you want to follow the interactive wizard. It asks for the required fields, shows examples, and makes explicit which values must be provided.

$ zenifra create project

Wizard interativo de criacao de projeto Zenifra
Digite ? para ajuda detalhada em qualquer campo.

? Nome do projeto: app-api
? Descricao: API principal do produto
? Tipo do projeto: http
? Plano: free
? Modo de pagamento: hourly
? Origem do deploy HTTP: github
? Porta da aplicacao: 3000
? Quantidade de instancias: 1
? Deseja adicionar variaveis de ambiente? sim
? Nome da env: NODE_ENV
? Valor da env: production
? Deseja adicionar mais um item? nao
? Exposicao HTTP: public
? Repository owner: minha-org
? Repository name: app-api
? Branch: main
? Runtime: nodejs
? Versao do runtime: 24
? Modo de deploy GitHub: branch
? Start command: npm start
? Pre build command:
? Build command: npm run build

Resumo da criacao
  projeto: app-api | plano: free | pagamento: hourly
  tipo: http
  descricao: API principal do produto
  http: exposicao public | porta 3000 | instancias 1 | storage 1Gi (efemero)
  github: minha-org/app-api@main | runtime nodejs@24
? Confirmar criacao do projeto: sim

Campo    Valor
-------  --------------------------------------
Projeto  507f1f77bcf86cd799439012
Dominio  https://app-api.clients.zenifra.com

The command above is a simulated flow; the CLI shows its prompts in Portuguese. Prompts depend on the plan: on Free, the wizard does not ask for persistent storage, auto-scaling, or a custom subdomain. The wizard offers the github and oci sources; for a Forgejo source, use --config with source and build, as in the example below. Real values should match your repository, plan, port, runtime, and variables. The URL returned by the command is the source of truth for accessing the project; do not construct a URL by assuming a default domain.

Common examples

List HTTP projects:

zenifra projects --type http --page 1 --limit 15

Project listing is paginated by default with 15 items per page. Use --page <n> to navigate; use --limit <n> when automation needs a different page size.

Create a project from a configuration file:

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

For a Git source, the configuration file uses source and build. The IDs below are examples: replace them with IDs returned by the organization's connection and repository selection.

{
  "type_project": "http",
  "exposure": "public",
  "source": {
    "connection_id": "connection-id-from-console",
    "repository_id": "repository-id-from-connection",
    "branch": "main",
    "auto_deploy": true
  },
  "build": {
    "runtime": "nodejs",
    "version": "24",
    "start_command": "npm start",
    "pre_build_command": null,
    "build_command": "npm run build"
  },
  "port": 3000
}

Do not include a repository token in the project file. Configure source connections through the organization's secure connection flow. For Forgejo, see Deploy from Forgejo and the Git connections reference.

On older APIs, confirming that an existing project uses a GitHub source may require project.read. The CLI does not treat denied access as proof of the source or try an alternate route. Forgejo requires an API that advertises the compatible Git source contract.

In HTTP project configuration files, set exposure: "public" to create a public route/domain or exposure: "private" to keep the application without internet exposure.

After creation, change exposure with:

zenifra project exposure set --project <project-id> --exposure public
zenifra project exposure set --project <project-id> --exposure private

Use private for automations, internal jobs, and apps that do not need public traffic.

Trigger a deploy:

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

Watch that build:

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

Reopen logs for a specific build:

zenifra builds logs --project <project-id> --build <build-id>
zenifra builds logs --project <project-id> --build <build-id> --follow

List existing builds:

zenifra builds --project <project-id>

Use builds when you need to discover a build_id. Use deploy watch when you already have a specific build to follow.

Detailed log entries use the event source and retain the build step and sequence. If only a final diagnostic is available, the summary source explains that detailed events were unavailable for that build.

Inspect plans before creating:

zenifra plans --type http

Human-readable output lists the capabilities available with the plan, such as logs, metrics, health checks, autoscaling, custom subdomains, and network access. For automation, use zenifra plans --type http --json: the capabilities object returns those availabilities as booleans. Inspect the plan before creating the project because effective capabilities depend on the returned plan.

Project identity and lifecycle

View the safe session identity and selected organization:

zenifra whoami
zenifra whoami --json

Human-readable output shows the profile name, API base, authentication mode, selected organization, and, when available, the organization's public name. JSON output provides the same data for scripts and never shows credentials.

Stop, resume, or delete a project with the ID returned by creation or listing:

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

stop and resume read the project after the operation to show the confirmed state. Deletion requires --yes, including in automation, to make destructive intent explicit. All three commands accept --json when another program will process the output.

Security

• use ZENIFRA_API_KEY in CI provider secrets;
• configure IP allowlists when the runner has a fixed IP;
• grant only the required permissions;
• rotate and revoke old keys.

Next steps

• Zenifra CLI
• Organization API Keys
• GitHub deployments
• Automatic by branch