Skip to main content

System Administration (CLI)

On a self-hosted deployment you own the system-wide operational settings, and you can change them live, without asking us to redeploy. You administer these with the DocAI Fabric CLI, which you install straight from your own running deployment so it always matches your version.

This page covers the one-time setup: installing the CLI, pointing it at your deployment, and optionally enabling an AI agent to drive it. Once that is done, each individual task has its own short guide, starting with Configure SMTP.

Who can do this​

System settings are system-wide, not tenant settings. They are reachable only with your deployment's admin API key (ADMIN_API_KEY). No regular user, not even a tenant administrator, can see or change them. Keep the admin key safe.

How you obtain this key depends on how your deployment is run:

  • Managed in Azure by the DocAI Fabric team: we provision the admin key as part of your deployment and share it with you securely during onboarding.
  • Self-hosted on-premises: you create ADMIN_API_KEY yourself when you deploy (it is one of your deployment environment variables), so you already hold it.

Step 1: Install the CLI from your deployment​

The CLI is served by your deployment, so the version always matches the running system.

One line:

curl -fsSL https://app.docaifabric.com/cli/install.sh | sh

This installs two equivalent commands: docaifabric and the short alias da. Check it:

da --help

Prefer pip yourself? Ask the deployment for the exact install command (it includes the current version), then run it:

curl -s https://app.docaifabric.com/cli/info
# use the "install_command" value it returns, for example:
# pip install https://app.docaifabric.com/cli/download/docaifabric_cli-1.1.0-py3-none-any.whl

Step 2: Point the CLI at your deployment​

The CLI needs your deployment URL and admin key. Set them as environment variables:

export DOCAIFABRIC_API_URL="https://app.docaifabric.com"
export DOCAIFABRIC_ADMIN_API_KEY="your-admin-api-key"

Or put them in a .env.cli file in your working directory:

DOCAIFABRIC_API_URL=https://app.docaifabric.com
DOCAIFABRIC_ADMIN_API_KEY=your-admin-api-key

Step 3: Let your AI agent do it (optional)​

An AI agent that runs commands on your computer, such as Claude Code or Codex, can drive these commands for you. Tell it your deployment's address, for example "administer our DocAI Fabric at https://app.docaifabric.com". It reads https://app.docaifabric.com/llms.txt, which tells it to install this CLI and read the playbook the deployment serves for its version:

da skill show system-administration

You can then simply ask, for example, "configure SMTP for this deployment" or "why are invitation emails not sending". Keep the admin key in the environment variables above: the agent never needs to see it, and the playbook tells it never to put a secret on the command line.

Over MCP​

An agent can also administer the deployment as an MCP server, without a shell: the admin MCP server at https://app.docaifabric.com/mcp/admin covers system settings, tenants, single sign-on, models and the audit log. It accepts only the admin key, which it reads from your environment:

# Claude Code
claude mcp add --scope user --transport http docaifabric-admin https://app.docaifabric.com/mcp/admin \
  --header "X-API-Key: $DOCAIFABRIC_ADMIN_API_KEY"
# OpenAI Codex: ~/.codex/config.toml
[mcp_servers.docaifabric-admin]
url = "https://app.docaifabric.com/mcp/admin"
bearer_token_env_var = "DOCAIFABRIC_ADMIN_API_KEY"
tool_timeout_sec = 600  # a model test can take minutes

It is a separate server from the one your users connect to at /mcp, which works inside one tenant and never accepts the admin key. Three rules hold on it:

  • Secrets never pass through it. The agent cannot set the SMTP password or a single sign-on client secret, and never sees a one-time password: it tells you the da admin command to run, which asks for the value with the input hidden.
  • Deletions wait for you. Deleting a tenant, a single sign-on connection or a domain, or purging the audit log, first returns what would be deleted (for a tenant, only once you have exported its whole audit log, which is deleted with it), and happens only when the agent confirms it with the token it got, which it is told to do only with your agreement.
  • Every change is recorded in the security audit log, as a call made with the admin key, with your agent's address.

Two jobs stay with the CLI: exporting the audit log, which writes a file on your machine (the agent can read the same records), and the migrations after an update. Reading the audit log through the agent sends the records it reads to the agent's model provider, as any tool result does.

What you can administer​

Each operation has its own short guide:

  • Configure SMTP - outbound email for invitations and password resets.
  • Configure the application URL - the public address used in the links inside those emails.
  • Tenants and sign-up - create, list and delete tenants, and control whether the public can create their own.
  • Test and measure models - check that the platform's models (or a tenant's) can do their work, and measure their speed and capacity.
  • Audit log and retention - read the deployment's own security audit stream, forward it to your SIEM, set how long every tenant's audit log is kept, set the operator notification address, and clear a sign-in block.
  • Set up single sign-on - connect the deployment to your organization's identity provider (OpenID Connect, for example Microsoft Entra ID or Okta), so people sign in with it in every tenant, and map the provider's groups to each tenant's user groups. A tenant's administrators can also set up their own connection on the Security page.
  • Step settings conversion: the application converts every project by itself after an update; da admin migrations status lists the projects and published versions whose step settings have moved onto their workflow's steps and says why any has not. See Getting updates.
  • Encryption key rotation: the application re-encrypts saved secrets under a new CREDENTIAL_ENCRYPTION_KEY when it starts; da admin credentials status shows whether anything still needs the previous key. See Rotating the encryption key.

Set them up in that order. The links in your emails depend on the application URL, and creating a tenant sends an email, so a working mail setup comes first.

More operations will be added here over time.

Logs are not part of the CLI: you read them with the tools your platform already gives you. See Application Logs for an Azure subscription, or Application Logs (On-Premises) for a Docker install.

Troubleshooting the CLI​

  • 401 or 403: your admin key is missing or wrong. Check DOCAIFABRIC_ADMIN_API_KEY matches the deployment's ADMIN_API_KEY.
  • Connection refused or timeout: check DOCAIFABRIC_API_URL points at your running deployment and is reachable from where you run the CLI.
  • 404 on an admin route: your deployment predates this feature. Update to a build that includes the system administration API.

For problems specific to a task (for example SMTP), see that task's own guide.