Combine AIRCTRL tools

You do not need to choose one tool for an entire project. Use each tool for the part it handles best.

Use the dashboard for security decisions that require a person, such as membership, roles, Personal Access Tokens and Service Account credentials.
Use the CLI for interactive terminal work and to start local processes with decrypted records in memory.
Use the SDK when your application or script needs to call directly.
Use MCP when an agent needs to inspect or change resources under an approved identity.
Use the raw API when another language or platform cannot use the TypeScript SDK.

All surfaces enforce the same API permissions. Their local configuration is separate. The tools can use the same account, project and record IDs. A human PAT can also represent the same person across API, SDK, CLI and MCP. A Service Account bundle can represent the same machine across SDK, CLI and MCP. They do not automatically read each other’s configuration:

Configuration	Who reads it
`~/.airctrl/config.json` created by `airctrl login`	CLI only
`AIRCTRL_API_URL` and `AIRCTRL_TOKEN`	Your SDK application
`AIRCTRL_MCP_*` variables	The local MCP server
Active Service Account bundle	Only the process where you map its fields

Do not make an application read the CLI configuration file. That file belongs to the CLI and its shape is not an application integration contract. The SDK does not read the CLI login file, and MCP does not inherit it.

Local development without environment files

This is the simplest way to use records in a local application that already reads environment variables.

Prepare the records

Create a project in the dashboard and store the values your application needs. Give records names that produce clear environment keys. The CLI trims each name, converts it to uppercase and replaces characters outside A-Z, 0-9 and _ with _. For example, Database URL becomes DATABASE_URL. Choose names that remain unique after conversion. Names such as API URL and API-URL both become API_URL. An injected record also replaces an existing child-process variable with the same key.

airctrl login

The CLI stores the API URL, human PAT and optional default project in ~/.airctrl/config.json, outside your repository. It asks for the vault passphrase when it needs to decrypt records unless your approved runtime supplies AC_VAULT_PASSWORD. Confirm the project before launching the application:

airctrl record list --project "$PROJECT_ID" --limit 25

Start the application

airctrl run --project "$PROJECT_ID" -- npm run dev

The CLI decrypts accessible records locally and injects them only into the child process. Your application continues to use normal environment access:

const databaseUrl = process.env.DATABASE_URL

if (!databaseUrl) {
  throw new Error('DATABASE_URL is required')
}

No .env file is created. When a value changes in , restart the command to launch a new process with the current values.

airctrl run removes control variables such as AC_TOKEN and AC_VAULT_PASSWORD before starting the child. The application receives the selected project records, not the CLI credential that fetched them.

Use the CLI for setup and the SDK in code

The CLI is useful for finding IDs and checking access before you write integration code:

airctrl project accounts
airctrl project list --account "$AIRCTRL_ACCOUNT_ID"
airctrl record list --project "$PROJECT_ID" --limit 25

The SDK still needs its own explicit configuration:

import { createClient } from '@airctrl/sdk'

const airctrl = createClient({
  baseUrl: process.env.AIRCTRL_API_URL!,
  auth: process.env.AIRCTRL_TOKEN!,
})

Load those values through your operating system, deployment platform or approved secret storage. Do not copy them from the CLI file at runtime. Use this combination when the CLI helps a developer prepare or inspect , while the application must call after it starts. If the application only needs ordinary environment values, use airctrl run and omit the SDK.

Use the CLI to discover context for MCP

The CLI can help you find an account, project, record or gateway ID before asking an agent to work with it:

airctrl project list --account "$AIRCTRL_ACCOUNT_ID"
airctrl gateway list --project "$PROJECT_ID"

airctrl login does not sign MCP in. This separation prevents an agent from silently inheriting a developer’s terminal session. Configure MCP separately with AIRCTRL_MCP_* variables. Then make a natural-language request with the exact scope you found:

Show the active records in project "00000000-0000-4000-8000-000000000010".
Return names, formats and IDs only. Do not decrypt values or change anything.

MCP tool used: list_records

Use a Service Account in CI or a server

Do not use a human CLI login for an unattended workload.

Create the Service Account in the dashboard.
Assign the smallest custom role and project access it needs.
Share the required records with it when direct record access is needed.
Provision its credential in the dashboard.
Save the complete bundle in the deployment platform’s secret storage.
Map the same bundle into the SDK, CLI or MCP process that performs the work.

Use only one identity mode in each process. Do not combine a human PAT, human vault passphrase and Service Account capability fields. For the SDK, map the bundle directly:

const airctrl = createClient({
  baseUrl: bundle.baseUrl,
  auth: bundle.bearer,
  credential: {
    credentialId: bundle.credentialId,
    capPrivateKeyB64: bundle.capPrivateKeyB64,
  },
})

For the CLI, map the bundle to AC_API_BASE_URL, AC_TOKEN, AC_SA_CREDENTIAL_ID and AC_SA_CAP_PRIVATE_KEY_B64. For MCP, use the matching AIRCTRL_MCP_* variables described in Authentication. Service Account creation, role assignment and credential lifecycle remain dashboard-only. SDK, CLI and MCP use an active credential; they do not administer it.

Separate control-plane and application credentials

credentials and application credentials have different jobs:

A human PAT or Service Account token authenticates calls to the control plane.
A vault passphrase or Service Account capability decrypts records locally.
A gateway token authenticates an application to an gateway.
A provider credential lets that gateway call the selected AI provider.

Do not substitute one for another. For example, an OpenAI client receives a gateway token and gateway URL. It does not receive your PAT or stored OpenAI provider key.

Avoid these combinations

Do not assume airctrl login configures the SDK or MCP.
Do not parse ~/.airctrl/config.json from application code.
Do not expect airctrl run to pass control credentials to its child process.
Do not commit a .env file, PAT, Service Account bundle, vault passphrase or provider key.
Do not use a human PAT for CI when a least-privilege Service Account can perform the supported operation.
Do not ask an agent to search neighboring accounts, projects or IDs after a 403 or 404.

Troubleshoot a combined workflow

Problem	What it means	What to do
`cli_not_authenticated`	The CLI has no human login, complete Service Account environment or selected machine profile.	Run `airctrl login` for local human work, or supply one complete approved machine identity.
`cli_project_required`	The CLI cannot choose a project safely.	Pass `--project` or save a default project during human login.
`sa_run_requires_project`	A Service Account tried to rely on a human default project.	Pass the assigned project ID explicitly.
A variable is missing in the child process	The record is unavailable, its name produced a different key, or another normalized name collided with it.	List the project records and compare their normalized names before restarting the process.
`no_wrapper_for_caller`	The identity can reach the record metadata but cannot decrypt its data key.	Grant that human or Service Account access to the record in .
`sa_env_bundle_incomplete`	Only part of a Service Account credential was supplied, or fields from different identity modes were mixed.	Replace the environment with fields from one complete active bundle.
MCP reports the wrong identity type	MCP received a different variable set than expected.	Check MCP status, then correct the MCP client’s `AIRCTRL_MCP_*` configuration.
`403` or `not_authorized`	Authentication worked, but RBAC or resource access denied the action.	Request the required role or project grant in the dashboard. Do not retry unchanged.

Choose your next guide

Authentication explains human and machine identities.
Records and secrets covers decryption, injection, creation and sharing.
SDK overview shows direct application integration.
CLI overview explains terminal and process-injection behavior.
MCP setup connects an approved agent identity.
Feature availability shows which operations each identity can use.

​What the tools share

​Local development without environment files

​Prepare the records

​Sign in to the CLI

​Start the application

​Use the CLI for setup and the SDK in code

​Use the CLI to discover context for MCP

​Use a Service Account in CI or a server

​Separate control-plane and application credentials

​Avoid these combinations

​Troubleshoot a combined workflow

​Choose your next guide

What the tools share

Local development without environment files

Prepare the records

Sign in to the CLI

Start the application

Use the CLI for setup and the SDK in code

Use the CLI to discover context for MCP

Use a Service Account in CI or a server

Separate control-plane and application credentials

Avoid these combinations

Troubleshoot a combined workflow

Choose your next guide