apcore-cli

Terminal adapter for apcore. Execute AI-Perceivable modules from the command line.

TypeScript SDK	github.com/aipartnerup/apcore-cli-typescript
Python SDK	github.com/aipartnerup/apcore-cli-python
Spec repo	github.com/aipartnerup/apcore-cli
apcore core	github.com/aipartnerup/apcore

apcore-cli turns any apcore-based project into a fully featured CLI tool — with zero code changes to your existing modules.

┌──────────────────┐
│  nestjs-apcore   │  <- your existing apcore project (unchanged)
│  express-apcore  │
│  ...             │
└────────┬─────────┘
         │  extensions directory
         v
┌──────────────────┐
│   apcore-cli     │  <- just install & point to extensions dir
└───┬──────────┬───┘
    │          │
    v          v
 Terminal    Unix
 Commands    Pipes

Design Philosophy

• Zero intrusion -- your apcore project needs no code changes, no imports, no dependencies on apcore-cli
• Zero configuration -- point to an extensions directory, everything is auto-discovered
• Pure adapter -- apcore-cli reads from the apcore Registry; it never modifies your modules
• Unix-native -- JSON output for pipes, rich tables for terminals, STDIN input, shell completions

Installation

pnpm add apcore-cli apcore-js

Requires Node.js 18+ and apcore-js >= 0.13.0.

Quick Start

Zero-code approach

If you already have an apcore-based project with an extensions directory:

# Execute a module
apcore-cli --extensions-dir ./extensions math.add --a 42 --b 58

# Or set the env var once
export APCORE_EXTENSIONS_ROOT=./extensions
apcore-cli math.add --a 42 --b 58

All modules are auto-discovered. CLI flags are auto-generated from each module's JSON Schema.

Programmatic approach (TypeScript API)

import { createCli } from "apcore-cli";

// Build the CLI from your registry
const cli = createCli("./extensions");
cli.parse(process.argv);

Or use the LazyModuleGroup directly with Commander:

import { LazyModuleGroup, buildModuleCommand } from "apcore-cli";
import { Registry, Executor } from "apcore-js";

const registry = new Registry("./extensions");
registry.discover();
const executor = new Executor(registry);

const group = new LazyModuleGroup(registry, executor);
const cmd = group.getCommand("math.add");
cmd?.parse(process.argv);

Integration with Existing Projects

Typical apcore project structure

your-project/
├── extensions/          <- modules live here
│   ├── math/
│   │   └── add.ts
│   ├── text/
│   │   └── upper.ts
│   └── ...
├── your_app.ts          <- your existing code (untouched)
└── ...

Adding CLI support

No changes to your project. Just install and run:

pnpm add apcore-cli apcore-js
apcore-cli --extensions-dir ./extensions list
apcore-cli --extensions-dir ./extensions math.add --a 5 --b 10

STDIN piping (Unix pipes)

# Pipe JSON input
echo '{"a": 100, "b": 200}' | apcore-cli math.add --input -
# {"sum": 300}

# CLI flags override STDIN values
echo '{"a": 1, "b": 2}' | apcore-cli math.add --input - --a 999
# {"sum": 1001}

# Chain with other tools
apcore-cli sysutil.info | jq '.os, .hostname'

CLI Reference

apcore-cli [OPTIONS] COMMAND [ARGS]

Global Options

Option	Default	Description
--extensions-dir	./extensions	Path to apcore extensions directory
--log-level	WARNING	Logging: DEBUG, INFO, WARNING, ERROR
--version		Show version and exit
--help		Show help and exit

Built-in Commands

Command	Description
list	List available modules with optional tag filtering
describe <module_id>	Show full module metadata and schemas
exec <module_id>	Internal routing alias for module execution
completion <shell>	Generate shell completion script (bash/zsh/fish)
man <command>	Generate man page in roff format

Module Execution Options

When executing a module (e.g. apcore-cli math.add), these built-in options are always available:

Option	Description
--input -	Read JSON input from STDIN
--yes / -y	Bypass approval prompts
--large-input	Allow STDIN input larger than 10MB
--format	Output format: json or table
--sandbox	Run module in subprocess sandbox

Schema-generated flags (e.g. --a, --b) are added automatically from the module's input_schema.

Exit Codes

Code	Meaning
0	Success
1	Module execution error
2	Invalid CLI input
44	Module not found / disabled / load error
45	Schema validation error
46	Approval denied or timed out
47	Configuration error
48	Schema circular reference
77	ACL denied
130	Execution cancelled (Ctrl+C)

Configuration

apcore-cli uses a 4-tier configuration precedence:

1. CLI flag (highest): --extensions-dir ./custom
2. Environment variable: APCORE_EXTENSIONS_ROOT=./custom
3. Config file: apcore.yaml
4. Default (lowest): ./extensions

Environment Variables

Variable	Description	Default
APCORE_EXTENSIONS_ROOT	Path to extensions directory	./extensions
APCORE_CLI_AUTO_APPROVE	Set to 1 to bypass all approval prompts	(unset)
APCORE_CLI_LOGGING_LEVEL	CLI-specific log level (takes priority over APCORE_LOGGING_LEVEL)	WARNING
APCORE_LOGGING_LEVEL	Global apcore log level (fallback when APCORE_CLI_LOGGING_LEVEL is unset)	WARNING
APCORE_AUTH_API_KEY	API key for remote registry authentication	(unset)
APCORE_CLI_SANDBOX	Set to 1 to enable subprocess sandboxing	(unset)
APCORE_CLI_HELP_TEXT_MAX_LENGTH	Maximum characters for CLI option help text before truncation	1000

Config File (apcore.yaml)

extensions:
  root: ./extensions
logging:
  level: DEBUG
sandbox:
  enabled: false
cli:
  help_text_max_length: 1000

Features

• Auto-discovery -- all modules in the extensions directory are found and exposed as CLI commands
• Auto-generated flags -- JSON Schema input_schema is converted to --flag value CLI options with type validation
• Boolean flag pairs -- --verbose / --no-verbose from "type": "boolean" schema properties
• Enum choices -- "enum": ["json", "csv"] becomes --format json with Commander validation
• STDIN piping -- --input - reads JSON from STDIN, CLI flags override for duplicate keys
• TTY-adaptive output -- rich tables for terminals, JSON for pipes (configurable via --format)
• Approval gate -- TTY-aware HITL prompts for modules with requires_approval: true, with --yes bypass and 60s timeout
• Schema validation -- inputs validated against JSON Schema before execution, with $ref/allOf/anyOf/oneOf resolution
• Security -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing
• Shell completions -- apcore-cli completion bash|zsh|fish generates completion scripts with dynamic module ID completion
• Man pages -- apcore-cli man <command> generates roff-formatted man pages
• Audit logging -- all executions logged to ~/.apcore-cli/audit.jsonl with SHA-256 input hashing

How It Works

Mapping: apcore to CLI

apcore	CLI
module_id (math.add)	Command name (apcore-cli math.add)
description	--help text
input_schema.properties	CLI flags (--a, --b)
input_schema.required	Validated post-collection via ajv (required fields shown as [required] in --help)
annotations.requires_approval	HITL approval prompt

Architecture

User / AI Agent (terminal)
    |
    v
apcore-cli (the adapter)
    |
    +-- ConfigResolver       4-tier config precedence
    +-- LazyModuleGroup      Dynamic Commander command generation
    +-- schema_parser        JSON Schema -> Commander options
    +-- ref_resolver         $ref / allOf / anyOf / oneOf
    +-- approval             TTY-aware HITL approval
    +-- output               TTY-adaptive JSON/table output
    +-- AuditLogger          JSON Lines execution logging
    +-- Sandbox              Subprocess isolation
    |
    v
apcore Registry + Executor (your modules, unchanged)

API Overview

Classes: LazyModuleGroup, ConfigResolver, AuthProvider, ConfigEncryptor, AuditLogger, Sandbox

Functions: createCli, main, buildModuleCommand, validateModuleId, collectInput, schemaToCliOptions, reconvertEnumValues, resolveRefs, checkApproval, resolveFormat, formatModuleList, formatModuleDetail, formatExecResult, registerDiscoveryCommands, registerShellCommands, setAuditLogger, getAuditLogger, exitCodeForError, mapType, extractHelp, truncate

Errors: ApprovalTimeoutError, ApprovalDeniedError, AuthenticationError, ConfigDecryptionError, ModuleExecutionError, ModuleNotFoundError, SchemaValidationError

Development

git clone https://github.com/aipartnerup/apcore-cli-typescript.git
cd apcore-cli-typescript
pnpm install
pnpm test                        # 183 tests
pnpm build                       # compile TypeScript

License

Apache-2.0