Operator CLI

The AgenC Operator CLI provides commands for bootstrapping, monitoring, and maintaining operator runtime environments. This reference covers every command, its flags, output structure, exit codes, and remediation guidance.

Overview

Installation

Global Options

Commands

- onboard

- health

- doctor

- security

Configuration Reference

Environment Variables

Exit Codes

Troubleshooting

Overview

The Operator CLI is the primary interface for managing an AgenC runtime node. It handles first-time setup, ongoing health monitoring, automated diagnostics, and security auditing. All commands emit structured JSON when the --json flag is provided, making them suitable for CI/CD pipelines and monitoring integrations.

Source locations:

Command	Source
`onboard`	`runtime/src/cli/onboard.ts`
`health`	`runtime/src/cli/health.ts`
`doctor`	`runtime/src/cli/doctor.ts`
`security`	`runtime/src/cli/security.ts`

Installation

# Install the runtime package
npm install -g @agenc/runtime

# Verify the installation
agenc --version

After installation, the agenc binary is available globally. Run agenc --help to list all available commands.

Global Options

These flags apply to every command.

Flag	Type	Default	Description
`--config`	`string`	`.agenc-runtime.json`	Path to the runtime configuration file.
`--json`	`boolean`	`false`	Emit output as structured JSON instead of human-readable text.
`--verbose`	`boolean`	`false`	Enable verbose logging for debugging.
`--help`	`boolean`	`false`	Print usage information and exit.

The config file path resolution order is:

Explicit --config flag value
AGENC_RUNTIME_CONFIG environment variable
.agenc-runtime.json in the current working directory

Commands

onboard

Bootstrap the runtime CLI configuration for a new operator. This is the first command you should run after installing the runtime.

Usage:

bash

agenc onboard [options]

What it does:

Generates a default .agenc-runtime.json configuration file (or at the path specified by --config / AGENC_RUNTIME_CONFIG).
Detects whether a Solana wallet keypair exists.
Tests RPC endpoint reachability.
Runs schema validation against the generated (or existing) configuration.
Reports a summary of all checks with an overall exit code.

Options:

Flag	Type	Default	Description
`--force`	`boolean`	`false`	Overwrite an existing configuration file. Without this flag, onboard will not modify an existing config.
`--rpc`	`string`	`https://api.devnet.solana.com`	Solana RPC URL to write into the generated config.
`--store`	`string`	`sqlite`	Store backend type (`sqlite` or `memory`).
`--log-level`	`string`	`info`	Logging verbosity (`debug`, `info`, `warn`, `error`).

Examples:

bash

# Default onboarding (devnet, SQLite store)
agenc onboard

# Onboard targeting mainnet with force-overwrite
agenc onboard --rpc https://api.mainnet-beta.solana.com --force

# Onboard with custom config path
agenc onboard --config /etc/agenc/runtime.json

# Onboard with JSON output for scripting
agenc onboard --json

OnboardResult

The structured output returned when --json is provided.

typescript

interface OnboardResult {
  /** Absolute path to the configuration file that was written or detected. */
  configPath: string;

  /** True if a new configuration file was generated during this run. */
  configGenerated: boolean;

  /** True if a Solana wallet keypair was found. */
  walletDetected: boolean;

  /** True if the configured RPC endpoint responded successfully. */
  rpcReachable: boolean;

  /** Individual validation checks performed during onboarding. */
  checks: OnboardCheck[];

  /** Process exit code. 0 = success, 1 = warnings, 2 = failure. */
  exitCode: 0 | 1 | 2;
}

interface OnboardCheck {
  /** Human-readable name of the check. */
  name: string;

  /** Whether the check passed, produced a warning, or failed. */
  status: "pass" | "warn" | "fail";

  /** Descriptive message explaining the result. */
  message: string;
}

Example JSON output:

json

{
  "configPath": "/home/operator/.agenc-runtime.json",
  "configGenerated": true,
  "walletDetected": true,
  "rpcReachable": true,
  "checks": [
    {
      "name": "config_schema",
      "status": "pass",
      "message": "Configuration file is valid."
    },
    {
      "name": "wallet_detection",
      "status": "pass",
      "message": "Keypair found at ~/.config/solana/id.json."
    },
    {
      "name": "rpc_reachability",
      "status": "pass",
      "message": "RPC endpoint https://api.devnet.solana.com responded in 142ms."
    }
  ],
  "exitCode": 0
}

Default Generated Configuration

When agenc onboard creates a new config file, the following defaults are written:

json

{
  "rpcUrl": "https://api.devnet.solana.com",
  "storeType": "sqlite",
  "logLevel": "info",
  "outputFormat": "json",
  "strictMode": false
}

Field	Type	Default	Description
`rpcUrl`	`string`	`https://api.devnet.solana.com`	Solana JSON-RPC endpoint.
`storeType`	`"sqlite" \	"memory"`	`sqlite`	Persistence backend. SQLite for production, memory for testing.
`logLevel`	`"debug" \	"info" \	"warn" \	"error"`	`info`	Minimum log verbosity.
`outputFormat`	`"json" \	"text"`	`json`	Default output format for CLI commands.
`strictMode`	`boolean`	`false`	When true, warnings are promoted to failures (exit code 2).

Validation Checks

The onboard command runs the following checks after config generation:

Check	Description	Failure Behavior
Config schema	Validates the configuration file against the expected JSON schema.	Fails if required fields are missing or have invalid types.
Wallet detection	Searches for a Solana keypair at `~/.config/solana/id.json` or the path in `SOLANA_KEYPAIR_PATH`.	Warns if no wallet is found. The operator can still onboard but will not be able to sign transactions.
RPC reachability	Sends a `getVersion` RPC call to the configured endpoint using `@solana/web3.js` `Connection`.	Warns on timeout; fails if the endpoint is unreachable or returns an error.

health

Run a comprehensive suite of health checks against the operator runtime and its dependencies. This command is designed for use in monitoring pipelines, readiness probes, and manual diagnostics.

Usage:

bash

agenc health [options]

Options:

Flag	Type	Default	Description
`--json`	`boolean`	`false`	Output the full `HealthReport` as JSON.
`--category`	`string`	all	Run only checks in a specific category (`rpc`, `store`, `wallet`, `config`, `program`, `capability`).
`--timeout`	`number`	`10000`	Timeout in milliseconds for network-dependent checks.

Examples:

bash

# Run all health checks with human-readable output
agenc health

# JSON output for monitoring integration
agenc health --json

# Check only RPC connectivity
agenc health --category rpc

# Check with a shorter timeout
agenc health --timeout 5000

HealthCheckResult

Each individual check produces a HealthCheckResult:

typescript

interface HealthCheckResult {
  /** Unique identifier for this check (e.g., "rpc_reachability"). */
  id: string;

  /** Functional category grouping related checks. */
  category: "rpc" | "store" | "wallet" | "capability" | "config" | "program";

  /** Outcome of the check. */
  status: "pass" | "warn" | "fail";

  /** Human-readable description of what was checked and the result. */
  message: string;

  /** Suggested action to resolve a warning or failure. Present only when status is not "pass". */
  remediation?: string;

  /** Wall-clock duration of this check in milliseconds. Present for network or I/O checks. */
  durationMs?: number;
}

HealthReport

The top-level report aggregates all individual checks:

typescript

interface HealthReport {
  /** Overall status derived from the worst individual check status. */
  status: "healthy" | "degraded" | "unhealthy";

  /** Array of all individual check results. */
  checks: HealthCheckResult[];

  /** ISO-8601 timestamp of when the report was generated. */
  timestamp: string;

  /** Process exit code. 0 = healthy, 1 = degraded, 2 = unhealthy. */
  exitCode: 0 | 1 | 2;
}

Status derivation rules:

healthy -- All checks passed.

degraded -- At least one check produced a warning, but no check failed.

unhealthy -- At least one check failed.

Example JSON output:

json

{
  "status": "degraded",
  "checks": [
    {
      "id": "rpc_reachability",
      "category": "rpc",
      "status": "pass",
      "message": "RPC endpoint https://api.devnet.solana.com is reachable.",
      "durationMs": 138
    },
    {
      "id": "rpc_latency",
      "category": "rpc",
      "status": "warn",
      "message": "RPC latency is 487ms, which exceeds the 400ms threshold.",
      "remediation": "Consider switching to a closer or less congested RPC endpoint.",
      "durationMs": 487
    },
    {
      "id": "store_directory",
      "category": "store",
      "status": "pass",
      "message": "SQLite data directory exists and is writable."
    },
    {
      "id": "store_integrity",
      "category": "store",
      "status": "pass",
      "message": "SQLite integrity check (PRAGMA integrity_check) passed.",
      "durationMs": 12
    },
    {
      "id": "wallet_keypair",
      "category": "wallet",
      "status": "pass",
      "message": "Wallet keypair loaded from ~/.config/solana/id.json."
    },
    {
      "id": "config_schema",
      "category": "config",
      "status": "pass",
      "message": "Configuration file schema is valid."
    },
    {
      "id": "program_idl",
      "category": "program",
      "status": "pass",
      "message": "IDL deserialization succeeded for agenc_coordination.",
      "durationMs": 4
    }
  ],
  "timestamp": "2026-02-15T14:30:00.000Z",
  "exitCode": 1
}

Check Categories in Detail

RPC Checks

These checks validate connectivity and performance of the configured Solana RPC endpoint. They use @solana/web3.js Connection internally.

Check ID	What It Does	Pass	Warn	Fail
`rpc_reachability`	Calls `getVersion()` on the RPC endpoint.	Responds within timeout.	--	Endpoint unreachable or times out.
`rpc_latency`	Measures round-trip time of a `getVersion()` call.	Latency under 400ms.	Latency between 400ms and 2000ms.	Latency exceeds 2000ms or request fails.

Store Checks

These checks validate the persistence layer.

Check ID	What It Does	Pass	Warn	Fail
`store_directory`	Verifies the SQLite data directory exists and is writable.	Directory exists with write permissions.	--	Directory missing or not writable.
`store_integrity`	Runs `PRAGMA integrity_check` against the SQLite database.	Pragma returns `ok`.	--	Pragma reports corruption.
`store_memory`	Validates in-memory store initialization (when `storeType` is `memory`).	Store initializes without error.	--	Initialization throws.

Note: The store_directory and store_integrity checks only run when storeType is sqlite. The store_memory check only runs when storeType is memory.

Wallet Checks

Check ID	What It Does	Pass	Warn	Fail
`wallet_keypair`	Loads the Solana keypair from `~/.config/solana/id.json` or the path specified by `SOLANA_KEYPAIR_PATH`.	Keypair file exists and is a valid JSON keypair.	--	File missing, unreadable, or contains invalid data.

Config Checks

Check ID	What It Does	Pass	Warn	Fail
`config_schema`	Validates the runtime configuration file against the expected schema.	All required fields present with valid types.	--	Schema validation errors found.

Program Checks

Check ID	What It Does	Pass	Warn	Fail
`program_idl`	Deserializes the AgenC Coordination IDL to verify it can be loaded by the runtime.	IDL parses without error.	--	IDL file missing or deserialization fails.

doctor

Extends health with automated remediation capabilities. Where health only reports problems, doctor can fix them.

Usage:

bash

agenc doctor [options]

Options:

Flag	Type	Default	Description
`--fix`	`boolean`	`false`	Apply automatic fixes for detected issues. Without this flag, doctor runs in report-only mode (identical to `health`).
`--dry-run`	`boolean`	`false`	Preview fixes that would be applied without making changes. Requires `--fix`.
`--json`	`boolean`	`false`	Output the report as JSON.
`--category`	`string`	all	Restrict checks and fixes to a specific category.

Examples:

bash

# Report issues without fixing (same as `agenc health`)
agenc doctor

# Preview what fixes would be applied
agenc doctor --fix --dry-run

# Apply all available auto-fixes
agenc doctor --fix

# Fix only store-related issues
agenc doctor --fix --category store

# JSON output with dry-run for CI
agenc doctor --fix --dry-run --json

Auto-Remediation Actions

The following issues can be automatically resolved by agenc doctor --fix:

Issue	Fix Applied	Category
SQLite data directory does not exist.	Creates the directory with appropriate permissions (`0750`).	`store`
Configuration file is missing.	Generates a default `.agenc-runtime.json` with standard defaults (equivalent to running `agenc onboard`).	`config`
Configuration file has invalid permissions.	Sets file permissions to `0600` (owner read/write only).	`config`

Dry-run output example:

bash

$ agenc doctor --fix --dry-run
[dry-run] Would create directory: /home/operator/.agenc/data/
[dry-run] Would set permissions 0750 on: /home/operator/.agenc/data/
[dry-run] Would generate default config: /home/operator/.agenc-runtime.json

3 fix(es) would be applied. Run without --dry-run to apply.

Fix output example:

bash

$ agenc doctor --fix
[fix] Created directory: /home/operator/.agenc/data/
[fix] Set permissions 0750 on: /home/operator/.agenc/data/
[fix] Generated default config: /home/operator/.agenc-runtime.json

3 fix(es) applied. Re-run `agenc health` to verify.

Doctor JSON Output

When --json is provided, the output extends HealthReport with fix information:

json

{
  "status": "unhealthy",
  "checks": [
    {
      "id": "store_directory",
      "category": "store",
      "status": "fail",
      "message": "SQLite data directory /home/operator/.agenc/data/ does not exist.",
      "remediation": "Run `agenc doctor --fix` to create the directory.",
      "fix": {
        "action": "create_directory",
        "target": "/home/operator/.agenc/data/",
        "applied": false,
        "dryRun": true
      }
    }
  ],
  "timestamp": "2026-02-15T14:35:00.000Z",
  "exitCode": 2
}

security

Run security-focused checks that go beyond standard health monitoring. This command audits the operator environment for configuration weaknesses, exposed secrets, and permission issues.

Usage:

bash

agenc security [options]

Options:

Flag	Type	Default	Description
`--json`	`boolean`	`false`	Output the security report as JSON.
`--strict`	`boolean`	`false`	Treat all warnings as failures (exit code 2).

Examples:

bash

# Run a security audit
agenc security

# JSON output for automated compliance checks
agenc security --json

# Strict mode for CI enforcement
agenc security --strict

Security Checks

Check ID	Description	Pass	Warn	Fail
`keypair_permissions`	Verifies the wallet keypair file has restrictive permissions (owner-only read).	Permissions are `0400` or `0600`.	Permissions are group-readable (`0640`).	Permissions are world-readable (`0644` or broader).
`config_permissions`	Verifies the configuration file is not world-readable.	Permissions are `0600` or more restrictive.	--	World-readable configuration detected.
`rpc_tls`	Checks that the RPC URL uses HTTPS.	URL scheme is `https://`.	--	URL scheme is `http://` (unencrypted).
`env_secrets`	Scans for secrets potentially leaked in environment variables.	No sensitive values detected in common env vars.	Potential secret found in a non-standard env var.	Private key material found in environment variables.

The security report follows the same HealthReport structure as the health command, with all check IDs prefixed for the security domain.

Configuration Reference

The runtime configuration file (.agenc-runtime.json) supports the following fields:

typescript

interface RuntimeConfig {
  /** Solana JSON-RPC endpoint URL. */
  rpcUrl: string;

  /** Persistence backend. */
  storeType: "sqlite" | "memory";

  /** Minimum logging verbosity. */
  logLevel: "debug" | "info" | "warn" | "error";

  /** Default output format for CLI commands. */
  outputFormat: "json" | "text";

  /** When true, warnings are treated as failures. */
  strictMode: boolean;
}

Full example:

json

{
  "rpcUrl": "https://api.mainnet-beta.solana.com",
  "storeType": "sqlite",
  "logLevel": "warn",
  "outputFormat": "json",
  "strictMode": true
}

Environment Variables

The following environment variables influence CLI behavior. Explicit flags always take precedence.

Variable	Description	Default
`AGENC_RUNTIME_CONFIG`	Absolute path to the runtime configuration file.	`.agenc-runtime.json` (current directory)
`SOLANA_KEYPAIR_PATH`	Absolute path to the Solana wallet keypair JSON file.	`~/.config/solana/id.json`
`LOG_LEVEL`	Override the `logLevel` field from the config file.	Value from config

Example: using environment variables in a deployment script:

bash

export AGENC_RUNTIME_CONFIG=/etc/agenc/runtime.json
export SOLANA_KEYPAIR_PATH=/etc/agenc/keypair.json

agenc health --json

Exit Codes

All commands follow a consistent exit code scheme:

Code	Meaning	When It Occurs
`0`	Success / Healthy	All checks passed. Onboarding completed without issues.
`1`	Degraded / Warnings	At least one check produced a warning but nothing failed. Non-critical issues detected.
`2`	Failure / Unhealthy	At least one check failed. The runtime is not operational or onboarding could not complete.

When strictMode is enabled (in config or via --strict), any warning is promoted to a failure, and the exit code becomes 2 instead of 1.

Using exit codes in scripts:

bash

agenc health --json
status=$?

if [ $status -eq 0 ]; then
  echo "Runtime is healthy."
elif [ $status -eq 1 ]; then
  echo "Runtime is degraded. Check warnings."
elif [ $status -eq 2 ]; then
  echo "Runtime is unhealthy. Immediate action required."
fi

Troubleshooting

Onboard fails with "config already exists"

The onboard command will not overwrite an existing configuration file by default. Use the --force flag to regenerate it:

bash

agenc onboard --force

RPC check fails with timeout

The default timeout is 10 seconds. If your RPC endpoint is slow, increase the timeout:

bash

agenc health --timeout 20000

If the endpoint is consistently unreachable, verify the URL in your configuration:

bash

cat .agenc-runtime.json | jq '.rpcUrl'

Wallet not detected

The CLI looks for a keypair at ~/.config/solana/id.json by default. If your keypair is elsewhere, set the environment variable:

bash

export SOLANA_KEYPAIR_PATH=/path/to/your/keypair.json
agenc health

To generate a new keypair:

bash

solana-keygen new -o ~/.config/solana/id.json

SQLite integrity check fails

If store_integrity reports corruption, you may need to rebuild the database:

bash

# Back up the existing database
cp ~/.agenc/data/store.db ~/.agenc/data/store.db.bak

# Remove and let the runtime recreate it
rm ~/.agenc/data/store.db

# Re-run doctor to recreate the data directory structure
agenc doctor --fix

Permission denied on config or keypair

Ensure the files have appropriate ownership and permissions:

bash

# Configuration file: owner read/write only
chmod 600 .agenc-runtime.json

# Keypair file: owner read only
chmod 400 ~/.config/solana/id.json

Run agenc security to verify that permissions meet security requirements.

IDL deserialization fails

This typically indicates a version mismatch between the runtime and the deployed program. Ensure your @agenc/runtime package version matches the on-chain program version:

# Check installed runtime version
agenc --version

# Reinstall the correct version
npm install -g @agenc/runtime@<version>

Refer to the Version Map for version compatibility details.

Command Quick Reference

text

agenc onboard [--force] [--rpc <url>] [--store <type>] [--log-level <level>] [--config <path>] [--json]
agenc health  [--json] [--category <cat>] [--timeout <ms>]
agenc doctor  [--fix] [--dry-run] [--json] [--category <cat>]
agenc security [--json] [--strict]

Operator CLI

- onboard

- health

- doctor

- security

Configuration Reference

Environment Variables

Exit Codes

Troubleshooting

Overview

Source locations:

Command	Source
`onboard`	`runtime/src/cli/onboard.ts`
`health`	`runtime/src/cli/health.ts`
`doctor`	`runtime/src/cli/doctor.ts`
`security`	`runtime/src/cli/security.ts`

Installation

# Install the runtime package
npm install -g @agenc/runtime

# Verify the installation
agenc --version

After installation, the agenc binary is available globally. Run agenc --help to list all available commands.

Global Options

These flags apply to every command.

Flag	Type	Default	Description
`--config`	`string`	`.agenc-runtime.json`	Path to the runtime configuration file.
`--json`	`boolean`	`false`	Emit output as structured JSON instead of human-readable text.
`--verbose`	`boolean`	`false`	Enable verbose logging for debugging.
`--help`	`boolean`	`false`	Print usage information and exit.

The config file path resolution order is:

Explicit --config flag value
AGENC_RUNTIME_CONFIG environment variable
.agenc-runtime.json in the current working directory

Commands

onboard

Bootstrap the runtime CLI configuration for a new operator. This is the first command you should run after installing the runtime.

Usage:

bash

agenc onboard [options]

What it does:

Generates a default .agenc-runtime.json configuration file (or at the path specified by --config / AGENC_RUNTIME_CONFIG).
Detects whether a Solana wallet keypair exists.
Tests RPC endpoint reachability.
Runs schema validation against the generated (or existing) configuration.
Reports a summary of all checks with an overall exit code.

Options:

Flag	Type	Default	Description
`--force`	`boolean`	`false`	Overwrite an existing configuration file. Without this flag, onboard will not modify an existing config.
`--rpc`	`string`	`https://api.devnet.solana.com`	Solana RPC URL to write into the generated config.
`--store`	`string`	`sqlite`	Store backend type (`sqlite` or `memory`).
`--log-level`	`string`	`info`	Logging verbosity (`debug`, `info`, `warn`, `error`).

Examples:

bash

# Default onboarding (devnet, SQLite store)
agenc onboard

# Onboard targeting mainnet with force-overwrite
agenc onboard --rpc https://api.mainnet-beta.solana.com --force

# Onboard with custom config path
agenc onboard --config /etc/agenc/runtime.json

# Onboard with JSON output for scripting
agenc onboard --json

OnboardResult

The structured output returned when --json is provided.

typescript

interface OnboardResult {
  /** Absolute path to the configuration file that was written or detected. */
  configPath: string;

  /** True if a new configuration file was generated during this run. */
  configGenerated: boolean;

  /** True if a Solana wallet keypair was found. */
  walletDetected: boolean;

  /** True if the configured RPC endpoint responded successfully. */
  rpcReachable: boolean;

  /** Individual validation checks performed during onboarding. */
  checks: OnboardCheck[];

  /** Process exit code. 0 = success, 1 = warnings, 2 = failure. */
  exitCode: 0 | 1 | 2;
}

interface OnboardCheck {
  /** Human-readable name of the check. */
  name: string;

  /** Whether the check passed, produced a warning, or failed. */
  status: "pass" | "warn" | "fail";

  /** Descriptive message explaining the result. */
  message: string;
}

Example JSON output:

json

{
  "configPath": "/home/operator/.agenc-runtime.json",
  "configGenerated": true,
  "walletDetected": true,
  "rpcReachable": true,
  "checks": [
    {
      "name": "config_schema",
      "status": "pass",
      "message": "Configuration file is valid."
    },
    {
      "name": "wallet_detection",
      "status": "pass",
      "message": "Keypair found at ~/.config/solana/id.json."
    },
    {
      "name": "rpc_reachability",
      "status": "pass",
      "message": "RPC endpoint https://api.devnet.solana.com responded in 142ms."
    }
  ],
  "exitCode": 0
}

Default Generated Configuration

When agenc onboard creates a new config file, the following defaults are written:

json

{
  "rpcUrl": "https://api.devnet.solana.com",
  "storeType": "sqlite",
  "logLevel": "info",
  "outputFormat": "json",
  "strictMode": false
}

Field	Type	Default	Description
`rpcUrl`	`string`	`https://api.devnet.solana.com`	Solana JSON-RPC endpoint.
`storeType`	`"sqlite" \	"memory"`	`sqlite`	Persistence backend. SQLite for production, memory for testing.
`logLevel`	`"debug" \	"info" \	"warn" \	"error"`	`info`	Minimum log verbosity.
`outputFormat`	`"json" \	"text"`	`json`	Default output format for CLI commands.
`strictMode`	`boolean`	`false`	When true, warnings are promoted to failures (exit code 2).

Validation Checks

The onboard command runs the following checks after config generation:

Check	Description	Failure Behavior
Config schema	Validates the configuration file against the expected JSON schema.	Fails if required fields are missing or have invalid types.
Wallet detection	Searches for a Solana keypair at `~/.config/solana/id.json` or the path in `SOLANA_KEYPAIR_PATH`.	Warns if no wallet is found. The operator can still onboard but will not be able to sign transactions.
RPC reachability	Sends a `getVersion` RPC call to the configured endpoint using `@solana/web3.js` `Connection`.	Warns on timeout; fails if the endpoint is unreachable or returns an error.

health

Run a comprehensive suite of health checks against the operator runtime and its dependencies. This command is designed for use in monitoring pipelines, readiness probes, and manual diagnostics.

Usage:

bash

agenc health [options]

Options:

Flag	Type	Default	Description
`--json`	`boolean`	`false`	Output the full `HealthReport` as JSON.
`--category`	`string`	all	Run only checks in a specific category (`rpc`, `store`, `wallet`, `config`, `program`, `capability`).
`--timeout`	`number`	`10000`	Timeout in milliseconds for network-dependent checks.

Examples:

bash

# Run all health checks with human-readable output
agenc health

# JSON output for monitoring integration
agenc health --json

# Check only RPC connectivity
agenc health --category rpc

# Check with a shorter timeout
agenc health --timeout 5000

HealthCheckResult

Each individual check produces a HealthCheckResult:

typescript

interface HealthCheckResult {
  /** Unique identifier for this check (e.g., "rpc_reachability"). */
  id: string;

  /** Functional category grouping related checks. */
  category: "rpc" | "store" | "wallet" | "capability" | "config" | "program";

  /** Outcome of the check. */
  status: "pass" | "warn" | "fail";

  /** Human-readable description of what was checked and the result. */
  message: string;

  /** Suggested action to resolve a warning or failure. Present only when status is not "pass". */
  remediation?: string;

  /** Wall-clock duration of this check in milliseconds. Present for network or I/O checks. */
  durationMs?: number;
}

HealthReport

The top-level report aggregates all individual checks:

typescript

interface HealthReport {
  /** Overall status derived from the worst individual check status. */
  status: "healthy" | "degraded" | "unhealthy";

  /** Array of all individual check results. */
  checks: HealthCheckResult[];

  /** ISO-8601 timestamp of when the report was generated. */
  timestamp: string;

  /** Process exit code. 0 = healthy, 1 = degraded, 2 = unhealthy. */
  exitCode: 0 | 1 | 2;
}

Status derivation rules:

healthy -- All checks passed.

degraded -- At least one check produced a warning, but no check failed.

unhealthy -- At least one check failed.

Example JSON output:

json

{
  "status": "degraded",
  "checks": [
    {
      "id": "rpc_reachability",
      "category": "rpc",
      "status": "pass",
      "message": "RPC endpoint https://api.devnet.solana.com is reachable.",
      "durationMs": 138
    },
    {
      "id": "rpc_latency",
      "category": "rpc",
      "status": "warn",
      "message": "RPC latency is 487ms, which exceeds the 400ms threshold.",
      "remediation": "Consider switching to a closer or less congested RPC endpoint.",
      "durationMs": 487
    },
    {
      "id": "store_directory",
      "category": "store",
      "status": "pass",
      "message": "SQLite data directory exists and is writable."
    },
    {
      "id": "store_integrity",
      "category": "store",
      "status": "pass",
      "message": "SQLite integrity check (PRAGMA integrity_check) passed.",
      "durationMs": 12
    },
    {
      "id": "wallet_keypair",
      "category": "wallet",
      "status": "pass",
      "message": "Wallet keypair loaded from ~/.config/solana/id.json."
    },
    {
      "id": "config_schema",
      "category": "config",
      "status": "pass",
      "message": "Configuration file schema is valid."
    },
    {
      "id": "program_idl",
      "category": "program",
      "status": "pass",
      "message": "IDL deserialization succeeded for agenc_coordination.",
      "durationMs": 4
    }
  ],
  "timestamp": "2026-02-15T14:30:00.000Z",
  "exitCode": 1
}

Check Categories in Detail

RPC Checks

These checks validate connectivity and performance of the configured Solana RPC endpoint. They use @solana/web3.js Connection internally.

Check ID	What It Does	Pass	Warn	Fail
`rpc_reachability`	Calls `getVersion()` on the RPC endpoint.	Responds within timeout.	--	Endpoint unreachable or times out.
`rpc_latency`	Measures round-trip time of a `getVersion()` call.	Latency under 400ms.	Latency between 400ms and 2000ms.	Latency exceeds 2000ms or request fails.

Store Checks

These checks validate the persistence layer.

Check ID	What It Does	Pass	Warn	Fail
`store_directory`	Verifies the SQLite data directory exists and is writable.	Directory exists with write permissions.	--	Directory missing or not writable.
`store_integrity`	Runs `PRAGMA integrity_check` against the SQLite database.	Pragma returns `ok`.	--	Pragma reports corruption.
`store_memory`	Validates in-memory store initialization (when `storeType` is `memory`).	Store initializes without error.	--	Initialization throws.

Note: The store_directory and store_integrity checks only run when storeType is sqlite. The store_memory check only runs when storeType is memory.

Wallet Checks

Check ID	What It Does	Pass	Warn	Fail
`wallet_keypair`	Loads the Solana keypair from `~/.config/solana/id.json` or the path specified by `SOLANA_KEYPAIR_PATH`.	Keypair file exists and is a valid JSON keypair.	--	File missing, unreadable, or contains invalid data.

Config Checks

Check ID	What It Does	Pass	Warn	Fail
`config_schema`	Validates the runtime configuration file against the expected schema.	All required fields present with valid types.	--	Schema validation errors found.

Program Checks

Check ID	What It Does	Pass	Warn	Fail
`program_idl`	Deserializes the AgenC Coordination IDL to verify it can be loaded by the runtime.	IDL parses without error.	--	IDL file missing or deserialization fails.

doctor

Extends health with automated remediation capabilities. Where health only reports problems, doctor can fix them.

Usage:

bash

agenc doctor [options]

Options:

Flag	Type	Default	Description
`--fix`	`boolean`	`false`	Apply automatic fixes for detected issues. Without this flag, doctor runs in report-only mode (identical to `health`).
`--dry-run`	`boolean`	`false`	Preview fixes that would be applied without making changes. Requires `--fix`.
`--json`	`boolean`	`false`	Output the report as JSON.
`--category`	`string`	all	Restrict checks and fixes to a specific category.

Examples:

bash

# Report issues without fixing (same as `agenc health`)
agenc doctor

# Preview what fixes would be applied
agenc doctor --fix --dry-run

# Apply all available auto-fixes
agenc doctor --fix

# Fix only store-related issues
agenc doctor --fix --category store

# JSON output with dry-run for CI
agenc doctor --fix --dry-run --json

Auto-Remediation Actions

The following issues can be automatically resolved by agenc doctor --fix:

Issue	Fix Applied	Category
SQLite data directory does not exist.	Creates the directory with appropriate permissions (`0750`).	`store`
Configuration file is missing.	Generates a default `.agenc-runtime.json` with standard defaults (equivalent to running `agenc onboard`).	`config`
Configuration file has invalid permissions.	Sets file permissions to `0600` (owner read/write only).	`config`

Dry-run output example:

bash

$ agenc doctor --fix --dry-run
[dry-run] Would create directory: /home/operator/.agenc/data/
[dry-run] Would set permissions 0750 on: /home/operator/.agenc/data/
[dry-run] Would generate default config: /home/operator/.agenc-runtime.json

3 fix(es) would be applied. Run without --dry-run to apply.

Fix output example:

bash

$ agenc doctor --fix
[fix] Created directory: /home/operator/.agenc/data/
[fix] Set permissions 0750 on: /home/operator/.agenc/data/
[fix] Generated default config: /home/operator/.agenc-runtime.json

3 fix(es) applied. Re-run `agenc health` to verify.

Doctor JSON Output

When --json is provided, the output extends HealthReport with fix information:

json

{
  "status": "unhealthy",
  "checks": [
    {
      "id": "store_directory",
      "category": "store",
      "status": "fail",
      "message": "SQLite data directory /home/operator/.agenc/data/ does not exist.",
      "remediation": "Run `agenc doctor --fix` to create the directory.",
      "fix": {
        "action": "create_directory",
        "target": "/home/operator/.agenc/data/",
        "applied": false,
        "dryRun": true
      }
    }
  ],
  "timestamp": "2026-02-15T14:35:00.000Z",
  "exitCode": 2
}

security

Run security-focused checks that go beyond standard health monitoring. This command audits the operator environment for configuration weaknesses, exposed secrets, and permission issues.

Usage:

bash

agenc security [options]

Options:

Flag	Type	Default	Description
`--json`	`boolean`	`false`	Output the security report as JSON.
`--strict`	`boolean`	`false`	Treat all warnings as failures (exit code 2).

Examples:

bash

# Run a security audit
agenc security

# JSON output for automated compliance checks
agenc security --json

# Strict mode for CI enforcement
agenc security --strict

Security Checks

Check ID	Description	Pass	Warn	Fail
`keypair_permissions`	Verifies the wallet keypair file has restrictive permissions (owner-only read).	Permissions are `0400` or `0600`.	Permissions are group-readable (`0640`).	Permissions are world-readable (`0644` or broader).
`config_permissions`	Verifies the configuration file is not world-readable.	Permissions are `0600` or more restrictive.	--	World-readable configuration detected.
`rpc_tls`	Checks that the RPC URL uses HTTPS.	URL scheme is `https://`.	--	URL scheme is `http://` (unencrypted).
`env_secrets`	Scans for secrets potentially leaked in environment variables.	No sensitive values detected in common env vars.	Potential secret found in a non-standard env var.	Private key material found in environment variables.

The security report follows the same HealthReport structure as the health command, with all check IDs prefixed for the security domain.

Configuration Reference

The runtime configuration file (.agenc-runtime.json) supports the following fields:

typescript

interface RuntimeConfig {
  /** Solana JSON-RPC endpoint URL. */
  rpcUrl: string;

  /** Persistence backend. */
  storeType: "sqlite" | "memory";

  /** Minimum logging verbosity. */
  logLevel: "debug" | "info" | "warn" | "error";

  /** Default output format for CLI commands. */
  outputFormat: "json" | "text";

  /** When true, warnings are treated as failures. */
  strictMode: boolean;
}

Full example:

json

{
  "rpcUrl": "https://api.mainnet-beta.solana.com",
  "storeType": "sqlite",
  "logLevel": "warn",
  "outputFormat": "json",
  "strictMode": true
}

Environment Variables

The following environment variables influence CLI behavior. Explicit flags always take precedence.

Variable	Description	Default
`AGENC_RUNTIME_CONFIG`	Absolute path to the runtime configuration file.	`.agenc-runtime.json` (current directory)
`SOLANA_KEYPAIR_PATH`	Absolute path to the Solana wallet keypair JSON file.	`~/.config/solana/id.json`
`LOG_LEVEL`	Override the `logLevel` field from the config file.	Value from config

Example: using environment variables in a deployment script:

bash

export AGENC_RUNTIME_CONFIG=/etc/agenc/runtime.json
export SOLANA_KEYPAIR_PATH=/etc/agenc/keypair.json

agenc health --json

Exit Codes

All commands follow a consistent exit code scheme:

Code	Meaning	When It Occurs
`0`	Success / Healthy	All checks passed. Onboarding completed without issues.
`1`	Degraded / Warnings	At least one check produced a warning but nothing failed. Non-critical issues detected.
`2`	Failure / Unhealthy	At least one check failed. The runtime is not operational or onboarding could not complete.

When strictMode is enabled (in config or via --strict), any warning is promoted to a failure, and the exit code becomes 2 instead of 1.

Using exit codes in scripts:

bash

agenc health --json
status=$?

if [ $status -eq 0 ]; then
  echo "Runtime is healthy."
elif [ $status -eq 1 ]; then
  echo "Runtime is degraded. Check warnings."
elif [ $status -eq 2 ]; then
  echo "Runtime is unhealthy. Immediate action required."
fi

Troubleshooting

Onboard fails with "config already exists"

The onboard command will not overwrite an existing configuration file by default. Use the --force flag to regenerate it:

bash

agenc onboard --force

RPC check fails with timeout

The default timeout is 10 seconds. If your RPC endpoint is slow, increase the timeout:

bash

agenc health --timeout 20000

If the endpoint is consistently unreachable, verify the URL in your configuration:

bash

cat .agenc-runtime.json | jq '.rpcUrl'

Wallet not detected

The CLI looks for a keypair at ~/.config/solana/id.json by default. If your keypair is elsewhere, set the environment variable:

bash

export SOLANA_KEYPAIR_PATH=/path/to/your/keypair.json
agenc health

To generate a new keypair:

bash

solana-keygen new -o ~/.config/solana/id.json

SQLite integrity check fails

If store_integrity reports corruption, you may need to rebuild the database:

bash

# Back up the existing database
cp ~/.agenc/data/store.db ~/.agenc/data/store.db.bak

# Remove and let the runtime recreate it
rm ~/.agenc/data/store.db

# Re-run doctor to recreate the data directory structure
agenc doctor --fix

Permission denied on config or keypair

Ensure the files have appropriate ownership and permissions:

bash

# Configuration file: owner read/write only
chmod 600 .agenc-runtime.json

# Keypair file: owner read only
chmod 400 ~/.config/solana/id.json

Run agenc security to verify that permissions meet security requirements.

IDL deserialization fails

This typically indicates a version mismatch between the runtime and the deployed program. Ensure your @agenc/runtime package version matches the on-chain program version:

# Check installed runtime version
agenc --version

# Reinstall the correct version
npm install -g @agenc/runtime@<version>

Refer to the Version Map for version compatibility details.

Command Quick Reference

text

agenc onboard [--force] [--rpc <url>] [--store <type>] [--log-level <level>] [--config <path>] [--json]
agenc health  [--json] [--category <cat>] [--timeout <ms>]
agenc doctor  [--fix] [--dry-run] [--json] [--category <cat>]
agenc security [--json] [--strict]

Operator CLI

Table of Contents

Overview

Installation

Global Options

Commands

onboard

OnboardResult

Default Generated Configuration

Validation Checks

health

HealthCheckResult

HealthReport

Check Categories in Detail

RPC Checks

Store Checks

Wallet Checks

Config Checks

Program Checks

doctor

Auto-Remediation Actions

Doctor JSON Output

security

Security Checks

Configuration Reference

Environment Variables

Exit Codes

Troubleshooting

Onboard fails with "config already exists"

RPC check fails with timeout

Wallet not detected

SQLite integrity check fails

Permission denied on config or keypair

IDL deserialization fails

Command Quick Reference

Command Palette

Operator CLI

Table of Contents

Overview

Installation

Global Options

Commands

onboard

OnboardResult

Default Generated Configuration

Validation Checks

health

HealthCheckResult

HealthReport

Check Categories in Detail

RPC Checks

Store Checks

Wallet Checks

Config Checks

Program Checks

doctor

Auto-Remediation Actions

Doctor JSON Output

security

Security Checks

Configuration Reference

Environment Variables

Exit Codes

Troubleshooting

Onboard fails with "config already exists"

RPC check fails with timeout

Wallet not detected

SQLite integrity check fails

Permission denied on config or keypair

IDL deserialization fails

Command Quick Reference