@enformik/cli

The Enformik CLI for CI pipelines and offline tools: publishes the website you build, sends application module (schema) changes for administrator approval, validates the manifest locally and generates a typed client. It has no runtime dependencies (Node.js ≥ 20).

npx @enformik/cli --help
# or install it permanently:
npm install -g @enformik/cli   # command: enformik

Working with an AI agent on your own machine (developing a module, looking at the app's structure, publishing to a development site) goes through the remote MCP server https://mcp.enformik.com/mcp: you connect your AI client to it and approve it in the console. The CLI has no personal sign-in and stores no credentials on your machine.

CI credentials

In order of precedence:

1. CI connection (recommended, no stored secret). Create a CI connection for the repository in the console (your application → CI connections) and set ENFORMIK_CI_RULE to its id. The CLI takes the job's OIDC identity from the CI provider, exchanges it at ENFORMIK_OAUTH_URL for a token of at most 15 minutes and keeps it in memory only:
   • GitHub Actions: the job needs permissions: id-token: write (the CLI reads ACTIONS_ID_TOKEN_REQUEST_URL / ACTIONS_ID_TOKEN_REQUEST_TOKEN).
   • GitLab CI/CD: define ENFORMIK_ID_TOKEN under id_tokens with aud set to the audience (ENFORMIK_AUDIENCE, default https://oauth.enformik.com).
   • Bitbucket Pipelines: add oidc: true (and the audience under oidc.audiences) to the step; the CLI reads BITBUCKET_STEP_OIDC_TOKEN.
   • Site commands need ENFORMIK_ENVIRONMENT (the website environment id; optional if the connection targets a single site); schema commands need ENFORMIK_APP (the application id) and use the connection's workspace unless ENFORMIK_WORKSPACE is set.
   • A GitLab job's / Bitbucket step's identity token can be exchanged only once: run one Enformik command that needs credentials per job (or step). GitHub issues a new identity token for every exchange.
2. A ready-made CI token: ENFORMIK_SITE_TOKEN / ENFORMIK_APP_TOKEN, when the job did the exchange itself (the console's CI connection examples do this).
3. Fallback for CIs without OIDC (e.g. Jenkins): ENFORMIK_DEPLOY_KEY (website; console: Developer site → Deploy keys, valid for at most 90 days) and ENFORMIK_CLIENT_ID + ENFORMIK_CLIENT_SECRET (application; console: your application → API access; role Schema upgrader, or Schema builder for the first installation).

Addresses: ENFORMIK_CONSOLE_URL (site commands) and ENFORMIK_APP_URL (schema commands).

# GitHub Actions
permissions: { id-token: write, contents: read }
steps:
  - uses: actions/checkout@v4
  - run: npm ci && npm run build
  - run: npx @enformik/cli@1 site deploy --dir dist
    env:
      ENFORMIK_CI_RULE: <CI connection id>
      ENFORMIK_ENVIRONMENT: <website environment id>
      ENFORMIK_CONSOLE_URL: https://console.enformik.com

enformik whoami shows which credential reaches which target (caller class, rule, owner, targets, scopes, expiry; with a fallback credential it says so). It decodes the CI token locally for diagnosis only and prints no secrets.

Site deployment

Requirements: Developer site must be enabled on your website environment in the Enformik management console.

npx @enformik/cli site deploy --dir dist

Rules such as whether index.html is at the root, whether there are hidden files (.env, .git…), whether the file types are allowed (executables, .zip/.iso and files without an extension are rejected), and whether the size/quota fits are checked before uploading; errors are shown with the file path. If a text file in the bundle contains a secret, the upload stops; you can skip a false alarm by listing the file in .enformikignore in the project root (one path per line, dir/ prefix, no wildcards). --expect-host <site-host> prevents deploying to the wrong site. On success the address of the new release is printed.

Schema (module) changes

npx @enformik/cli schema validate --manifest module.json        # local, no credentials
npx @enformik/cli schema install --manifest module.json --yes   # first installation (--dry-run: show only)
npx @enformik/cli schema diff --manifest module.json --check    # exit code 2 if there are changes
npx @enformik/cli schema push --manifest module.json --yes

Warning: a module (schema) change affects all workspaces in the application.

Every change goes to an administrator for approval. schema install and schema push apply nothing: the whole manifest is saved as a proposal, and it takes effect only when an administrator approves it in the app (Modules → Proposals). CI connections and API clients with the Administrator role cannot approve proposals. Keep roles, access rules and scripts in the manifest; do not split them out. Check the result with enformik schema status.

schema validate runs locally without credentials or network: JSON, module.slug/module.version, and the sections an administrator reviews closely (adminSections). The server's own rules (naming, structure) are checked by the MCP tool schema_validate, or by schema diff in CI.

Commands

Run enformik <command> --help for a command's usage. A mistyped command (enformik sitee --help) is an error, not the general help.

Global flags: --json, --config, --debug, -h/--help, -v/--version. Target flags: --console-url, --app-url, --workspace (override the environment variables).

--expect-host <host> stops the operation if the host name differs: in the schema commands it is the application's host, in site deploy and site status the site's host.

Exit codes

JSON output

With --json, stdout carries only JSON (human-readable text goes to stderr), so pipelines can parse it. Errors are JSON objects with error (a stable code) and message, for example unknown_command (with a hint for a removed command), usage, no_credentials, ci_rule_denied, ci_identity_missing, rate_limited (with status: 429 and, when the server sent one, retryAfterSeconds; the CLI does not retry a 429 by itself) or unexpected. Some commands report a failed outcome as their normal result instead (a declined confirmation is applied: false, a failed or rejected deployment is deployed: false with status, error or issues); in every case the exit code is 1, so branch on the exit code first and read error second.

Environment variables

Precedence is flag, then environment variable. Secrets are never read from a flag or the config file.

.enformik/config.json (committed to the repository) holds only the project layout: module.slug, module.manifest, site.dir, codegen.out. It contains no addresses and no secrets.

Upgrading to 1.0

1.0 is a breaking release: the CLI is now only for CI and offline tools.

• Removed commands: auth login|status|logout, env list|use|current|forget, link, ai init, app check and mcp. Use the remote MCP server (https://mcp.enformik.com/mcp) on your own machine; app check is its app_check tool and the guides are read through its docs_* tools. The @enformik/mcp package is discontinued.
• Removed: the credentials file (~/.config/enformik/credentials.json) and the project binding (.enformik/local.json); you can delete them. Credentials created by env use were revoked.
• Removed flags and variables: --env / ENFORMIK_ENV, --docs-url / ENFORMIK_DOCS_URL, ENFORMIK_NO_STORED_CREDENTIALS, ENFORMIK_CONFIG_DIR, and schema validate --profile / --offline (validation is always local now).
• Renamed: ENFORMIK_WORKSPACE_ID → ENFORMIK_WORKSPACE (the old name prints a warning and is ignored).
• .enformik/config.json no longer reads consoleUrl, appUrl or workspaceId (a warning names the variable to use).
• New: CI connections (ENFORMIK_CI_RULE), ready-made CI tokens (ENFORMIK_SITE_TOKEN, ENFORMIK_APP_TOKEN); whoami describes CI tokens.
• Deploy keys are valid for at most 90 days; longer keys were shortened to 90 days.

Security

• Secrets are never read from a command-line flag or a project file (a .enformik/config.json that contains a secret is rejected): they come from environment variables only.
• CI tokens are kept in memory only; they are never written to disk or printed.
• Credentials are sent only over HTTPS (except localhost); redirects are not followed.

Detailed guide: the "CLI" page in the Enformik developer documentation.