ACP Operational CLI Guide

acpctl is the standalone operational CLI for privileged ACP Engine maintenance. Use it from an authorized operator environment when an action cannot safely be exposed through Manager, such as database preflight, migration verification, or recovering a Manager account.

The operational CLI is different from the embedded Manager CLI:

Surface	Purpose	Access model
acpctl	Privileged maintenance actions	Authorized terminal with deployment secrets and database network access
Manager CLI	Read-only realm inspection	Authenticated Manager session and selected realm

acpctl does not require Docker. It can run as a standalone binary, a Kubernetes job, a virtual-machine utility, or an ephemeral tool container. The deployment team decides how the binary and its secrets are delivered.

Prerequisites

Before running an operational command, confirm that:

• The acpctl binary matches the deployed ACP Engine release.
• The operator terminal can reach the ACP PostgreSQL database.
• DB_URL is supplied through the deployment's approved secret-management mechanism.
• Interactive commands are run in a terminal that supports hidden input.
• The operator is authorized for the intended database or account operation.

Do not paste DB_URL, database credentials, or passwords into tickets, chat messages, shell history, or screenshots.

Kubernetes and Helm

ACP's Helm chart includes a disabled-by-default, one-shot operator Job. The Job reads DB_URL from the same Kubernetes Secret used by the ACP services; the operator does not enter or copy the database URL.

Render the Job with the values for the installed release, using a unique non-secret runId and the target Manager email, then create it in the ACP namespace. Attach an interactive terminal to the resulting Job to enter the temporary password at the hidden prompts.

The Job does not receive a Kubernetes API token, uses the chart's restricted security context, and is removed after its configured completion TTL. Do not enable it permanently in normal release values. With an external database, the deployment's approved network-egress policy must allow the database connection.

Refer to the Helm package delivered with the deployed ACP release for the exact render and attach commands. This avoids copying a command from a different chart version or namespace.

Database bootstrap and migration operations use separate release-matched Helm Jobs. They mount the exact init and migration assets packaged with the chart; do not reuse an operator image or SQL directory from another ACP release.

Database Preflight and Verification

The following commands inspect the target database without applying changes:

acpctl database schema report \
  --init RELEASE_INIT_SQL \
  --format jsonl

acpctl database migrations status \
  --dir RELEASE_MIGRATION_DIR

acpctl database migrations plan \
  --dir RELEASE_MIGRATION_DIR

acpctl database migrations verify \
  --dir RELEASE_MIGRATION_DIR

RELEASE_INIT_SQL and RELEASE_MIGRATION_DIR are paths from the exact release package or release-matched operator container. schema report emits one JSON object for every missing or incompatible schema object plus a final summary. Migration status and plan report the immutable ledger state, pending migrations, and checksum conflicts without creating or modifying the ledger.

schema doctor is also read-only but exits unsuccessfully when canonical gaps remain, making it suitable for a blocking verification gate:

acpctl database schema doctor --init RELEASE_INIT_SQL --format jsonl

Applying Database Migrations

Prefer the Helm update flow described in Helm Deployment and Updates. It enforces preflight, migration, verification, and workload ordering around the command.

An approved external database pipeline may invoke the same release-matched operation directly:

acpctl database migrations apply \
  --dir RELEASE_MIGRATION_DIR \
  --release RELEASE_VERSION \
  --backup-reference CHANGE_OR_SNAPSHOT_REFERENCE

Apply requires a non-secret backup/PITR or change reference, takes a PostgreSQL advisory lock, and runs each pending migration in its own transaction. Never edit or remove a migration after release. Resolve a shipped defect with a new forward migration.

Packaged migration names use VYYYYMMDDNNNN__name.sql; the final four digits sequence multiple migrations created on the same UTC date. Customers should not rename these files or assemble a migration directory from different ACP releases.

An installation without acp_schema_migrations is reported as UNTRACKED and is not modified automatically. The one-time untracked-baseline option may be used only after a read-only inventory, reviewed environment-specific diff, and verified recovery point. It is not a drift-repair option.

database schema bootstrap is reserved for the chart's first-install path. It installs the baseline only when no ACP tables exist and rejects partial or untracked databases. Do not run it manually to repair an existing schema.

Reset a Manager Password

Use this action when an active Manager user cannot sign in and normal account access cannot be restored.

acpctl manager password reset --email user@example.com

The CLI prompts for the new temporary password twice without echoing it. The password must contain between 10 and 1,024 characters.

The reset is applied as one database transaction:

1. The active Manager account is resolved by its normalized email address.
2. The new password is hashed before storage.
3. Existing password-reset tokens are cleared.
4. Every active Manager session for the account is revoked.
5. The account is marked to require a password change at the next sign-in.

The command does not accept a password through a command argument or environment variable.

Expected Result

A successful command reports that the Manager password was reset, existing sessions were revoked, and a password change is required at the next sign-in.

After the reset:

1. Give the temporary password to the intended user through an approved secure channel.
2. Ask the user to sign in to Manager.
3. Confirm that Manager requires a new password before allowing access to protected pages.
4. Confirm that an older session cannot access Manager.

Do not record the temporary password in the support ticket.

Troubleshooting

DB_URL is required : Supply the database connection through the deployment's approved secret-management mechanism. Do not add it to the command example or commit it to a file.

an interactive terminal is required : Run acpctl from a terminal that supports hidden password input. Non-interactive automation must not inject the password through arguments or environment variables.

active Manager user not found : Confirm the email address and verify that the Manager account is active. The command intentionally does not reset inactive accounts.

password must be at least 10 characters : Choose a longer temporary password and run the command again.

passwords do not match : Re-run the command and enter the same temporary password at both prompts.

connect to database : Verify database network reachability, TLS requirements, credentials, and the target database in DB_URL before retrying.

migration ledger is untracked : Stop the update. Inventory the existing schema and follow the approved one-time baseline review; do not replay init.sql.

migration checksum mismatch : Stop the update and restore the exact released migration package. Do not edit the database ledger or rewrite the shipped migration.

pending migrations remain : Do not roll application workloads forward. Apply the approved release migrations and rerun schema doctor and migration verify.

If the command fails before the transaction commits, treat the reset as unsuccessful and resolve the reported problem before retrying. Do not modify Manager credential tables manually as a shortcut.

Security Boundaries

• Restrict acpctl distribution and execution to trusted operators.
• Use a database identity with only the permissions required for the supported operation.
• Run the command against the intended environment; verify production versus non-production before entering a password.
• Keep database and terminal audit records according to the customer's retention policy, but never record password input.
• Document the reason, operator, environment, target account, and completion time in the customer's approved audit system.

Only commands listed in this guide are part of the documented customer operational surface. Additional maintenance actions must not be assumed from internal packages or database tables.