Records and secrets

A record stores one encrypted secret and its metadata. Record plaintext is encrypted and decrypted in the SDK, CLI, Web app, or local MCP process.

Choose the right surface

Use the SDK inside an application or script.
Use the CLI to inject records into a child process without writing a .env file.
Use MCP when an agent needs an approved action.
Use the raw API for metadata and pre-encrypted payloads. Prefer the SDK for values because it performs the required cryptography.

Read one record

SDK

const secret = await airctrl.getSecret({
  recordId: '00000000-0000-4000-8000-000000000100',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

console.log(secret.name)
console.log(secret.fields)

getSecret returns the decrypted value and parsed fields. The decryption happens in your process. Use readRecord when you want selected sections instead of the complete record:

const record = await airctrl.readRecord({
  recordId: '00000000-0000-4000-8000-000000000100',
  scope: ['meta', 'fields'],
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

CLI

Print only the secret value:

airctrl get 00000000-0000-4000-8000-000000000100

Read structured fields and metadata:

airctrl read 00000000-0000-4000-8000-000000000100 --scope meta,fields

MCP

The MCP server reads the vault passphrase from AIRCTRL_MCP_VAULT_PASSWORD, never from the prompt.

An agent can see values returned by a record tool. Only call a decryption tool when the model is allowed to receive that secret.

Read only the "username" and "password" fields from the production environment
of record "00000000-0000-4000-8000-000000000100". Use them only for this task.
Do not print, log or repeat their values in your response.

MCP tool used: read_record

Inject a project into a process

The CLI converts record names to uppercase environment variable names and injects them only into the child process.

airctrl run --project 00000000-0000-4000-8000-000000000010 -- node server.js

For example, Database URL becomes DATABASE_URL. control variables are removed before the child starts. SDK equivalent:

const records = await airctrl.getAll({
  projectId: '00000000-0000-4000-8000-000000000010',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

const environment = Object.fromEntries(
  records.map((record) => [record.name, record.value]),
)

MCP is different

MCP does not inject values into a child process. It returns tool results to the agent. Prefer the CLI when the goal is only to start an application without a .env file. A bulk MCP read exposes decrypted values to the agent, so use it only in an approved context. When the agent is explicitly allowed to use every accessible value in one project, ask:

Load every accessible record from project
"00000000-0000-4000-8000-000000000010" for this task. Use the values only as
runtime input. Do not print, summarize or retain them after the task.

MCP tool used: get_all

Create a record

Use createSecret with the fields required by the selected secret format:

const result = await airctrl.createSecret({
  projectId: '00000000-0000-4000-8000-000000000010',
  name: 'Payments database',
  secretFormat: 'database',
  fieldValues: {
    engine: 'postgresql',
    host: 'db.internal.example',
    port: '5432',
    database: 'payments',
    username: 'payments-app',
    password: process.env.SOURCE_DATABASE_PASSWORD!,
  },
  tags: ['payments', 'production'],
  idempotencyKey: '00000000-0000-4000-8000-000000000120',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

console.log(result.recordId)

CLI:

airctrl create database \
  --project 00000000-0000-4000-8000-000000000010 \
  --name "Payments database" \
  --field engine=postgresql \
  --field host=db.internal.example \
  --field port=5432 \
  --field database=payments \
  --field username=payments-app

Avoid placing sensitive field values directly in shell history. For files of environment variables, use:

airctrl import env ./source.env \
  --project 00000000-0000-4000-8000-000000000010 \
  --name "Payments environment" \
  --target-env production

MCP

Supply secret values only when the model is authorized to receive them.

Create a database record named "Payments database" in project
"00000000-0000-4000-8000-000000000010" using values from the approved local
secret source. Show the project, name, format and field names, but never the
field values. Wait for my confirmation before creating it.

MCP tool used: create_record

Generate a new secret

can generate supported material locally and store it in one operation. Supported generators include passwords, API keys, TOTP seeds, SSH keys, certificates, webhook secrets, and OAuth client secrets.

await airctrl.createGeneratedRecord({
  projectId,
  name: 'Webhook signing key',
  secretFormat: 'webhook',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

airctrl new webhook --project "$PROJECT_ID" --name "Webhook signing key"

MCP request:

Create a webhook secret named "Webhook signing key" in project
"00000000-0000-4000-8000-000000000010". Generate its value locally. Show only
the non-secret details and wait for my confirmation. Never print the generated
value.

MCP tools used: generate_secret, create_record

Update, rotate and roll back

setSecret saves a new encrypted value version.
rotateRecord creates a new data key and encrypted value.
rollbackRecordToVersion makes an earlier encrypted version current without deleting history.
updateRecordMetadata changes name, tags, due date, or rotation interval without changing the value.

CLI equivalents are set, record rotate, record rollback, and record metadata. MCP equivalents are set_secret, rotate_record, rollback_record, and update_record_metadata.

Sharing encrypts the record key for the recipient. It does not share your vault passphrase.The same pattern exists for Service Accounts and groups. CLI uses record share-user, share-sa, share-group and their matching revoke-* commands.

await airctrl.shareRecordWithUser({
  recordId,
  granteeUserId,
  permission: 'read',
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})

await airctrl.revokeRecordFromUser(recordId, granteeUserId)

MCP request:

Give user "00000000-0000-4000-8000-000000000050" read access to record
"00000000-0000-4000-8000-000000000020". Confirm both resources and wait for
my approval. After I confirm, change only this direct user grant.

To remove that direct grant later:

Remove user "00000000-0000-4000-8000-000000000050" from record
"00000000-0000-4000-8000-000000000020". Explain that access will end
immediately and wait for my confirmation. Do not change any other grant.

MCP tools used: share_record_user, revoke_record_user

History and audit

Use record versions, record audit, anomalies, activity, alerts, and access feeds to understand changes without exposing plaintext. Project-scoped audit feeds require audit:read.

Common failures

403 not_authorized: the caller lacks record access or the required action permission.
404 record_not_found: the ID is wrong or unavailable in the active account.
409 record_name_exists: another record already uses that name where uniqueness is required.
409 project_not_keyed: refresh project key state before retrying the operation.

​Choose the right surface

​Read one record

​SDK

​CLI

​MCP

​Inject a project into a process

​MCP is different

​Create a record

​MCP

​Generate a new secret

​Update, rotate and roll back

​Share and revoke

​History and audit

​Common failures

Choose the right surface

Read one record

SDK

CLI

MCP

Inject a project into a process

MCP is different

Create a record

MCP

Generate a new secret

Update, rotate and roll back

Share and revoke

History and audit

Common failures