Skip to content

Getting Started

This guide walks you through installing apcore-cli, running your first module, and building your own — all in under 5 minutes.

Prerequisites

  • Python 3.11+
  • An apcore project with an extensions directory, or the example modules from the Python SDK

Install

pip install apcore-cli

Verify the installation:

apcore-cli --version

Quick start with example modules

The Python SDK ships with 8 example modules you can use immediately:

git clone https://github.com/aipartnerup/apcore-cli-python.git
cd apcore-cli-python
pip install -e ".[dev]"

export APCORE_EXTENSIONS_ROOT=examples/extensions

Run a module:

apcore-cli math.add --a 5 --b 10
# {"sum": 15}

Discover modules

List all modules

apcore-cli list

In an interactive terminal you get a formatted table; when piped, output switches to JSON automatically.

Filter by tag

apcore-cli list --tag math

Inspect a module

apcore-cli describe math.add

This shows the module's description, input/output schemas, tags, and annotations (including requires_approval).

Execute modules

Basic execution

Flags are generated automatically from the module's input_schema:

apcore-cli math.add --a 42 --b 58
# {"sum": 100}

STDIN piping

Use --input - to read JSON from STDIN. CLI flags override duplicate keys:

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

# --a overrides the STDIN value
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'

Approval gate

Modules annotated with requires_approval: true will prompt for confirmation before execution. To bypass in scripts:

apcore-cli dangerous.operation --yes
# or
export APCORE_CLI_AUTO_APPROVE=1

Output format

Force a specific format regardless of TTY detection:

apcore-cli list --format json     # always JSON
apcore-cli list --format table    # always table

Write your first module

Create a Python file in your extensions directory:

# extensions/greet/hello.py
from pydantic import BaseModel


class Input(BaseModel):
    name: str
    greeting: str = "Hello"


class Output(BaseModel):
    message: str


class GreetHello:
    input_schema = Input
    output_schema = Output
    description = "Greet someone by name"

    def execute(self, inputs, context=None):
        return {"message": f"{inputs['greeting']}, {inputs['name']}!"}

Run it:

apcore-cli greet.hello --name World
# {"message": "Hello, World!"}

The module ID (greet.hello) is derived from the directory structure — no registration needed.

Schema-driven flags

--name is required (no default in Input), --greeting is optional with default "Hello". Boolean fields become --flag / --no-flag pairs. Enum fields become choice options with validation.

Configuration

apcore-cli resolves configuration in 4 tiers (highest wins):

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

Minimal config file

# apcore.yaml
extensions:
  root: ./extensions
logging:
  level: DEBUG
sandbox:
  enabled: false

Key environment variables

Variable Description Default
APCORE_EXTENSIONS_ROOT Path to extensions directory ./extensions
APCORE_CLI_AUTO_APPROVE Set 1 to bypass approval prompts (unset)
APCORE_LOGGING_LEVEL Log level (DEBUG, INFO, WARN, ERROR) INFO

For the full configuration reference, see the Config Resolver spec.

Shell completions

Generate and install completion scripts for your shell:

apcore-cli completion bash > ~/.apcore-cli-complete.bash
echo 'source ~/.apcore-cli-complete.bash' >> ~/.bashrc

apcore-cli completion zsh > ~/.apcore-cli-complete.zsh
echo 'source ~/.apcore-cli-complete.zsh' >> ~/.zshrc

apcore-cli completion fish > ~/.config/fish/completions/apcore-cli.fish

Common 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

For the full exit code reference, see the Tech Design Section 8.1.

Next steps