Skip to main content

​
The CLI Contract

Every AOS connector is a Python CLI tool that implements a standard interface. The contract is defined in the Harness Spec and enforced at runtime.

​
Global Flags

Every connector must support these flags:
FlagPurpose
--jsonOutput structured JSON instead of human-readable text
--mode <tier>Set the permission tier for this invocation
--verboseEnable detailed output
--versionPrint version and exit

​
Required Commands

Every connector must implement three built-in commands:
CommandPurpose
capabilities --jsonSelf-describe: tool name, version, supported modes, full command list
health --jsonReport readiness: healthy, needs_setup, degraded, or error
config show --jsonShow current configuration with secrets redacted

​
JSON Output Envelope

All connector output follows a standard envelope format:

​
Success

{
  "ok": true,
  "tool": "aos-github",
  "command": "issue.list",
  "data": {
    "issues": [
      { "number": 42, "title": "Fix login bug", "state": "open" }
    ]
  },
  "meta": {
    "mode": "readonly",
    "duration_ms": 234,
    "timestamp": "2026-03-31T12:00:00Z",
    "version": "1.0.0"
  }
}

​
Error

{
  "ok": false,
  "tool": "aos-github",
  "command": "issue.delete",
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Command requires mode=admin",
    "details": {
      "required_mode": "admin",
      "actual_mode": "readonly"
    }
  },
  "meta": {
    "mode": "readonly",
    "duration_ms": 3,
    "timestamp": "2026-03-31T12:00:01Z",
    "version": "1.0.0"
  }
}

​
Exit Codes

CodeMeaning
0Success
2Invalid usage / arguments
3Permission denied
4Auth / config error
5Backend unavailable
6Not found
10Internal error

​
Permission Model

Connectors enforce a four-tier permission model via the --mode flag:
ModeAccess LevelExamples
readonlyRead-only queries, no mutationsList issues, search contacts, view invoices
writeCreate and update operationsCreate ticket, send message, update record
fullAll operations including bulkBulk update, batch operations, imports
adminDestructive and configurationDelete records, revoke access, modify settings
Permission enforcement happens inside the command execution path, not just at the documentation level. Every command is mapped to a minimum mode in permissions.json: 
{
  "commands": {
    "issue.list": "readonly",
    "issue.create": "write",
    "issue.delete": "admin",
    "health": "readonly",
    "config.show": "readonly"
  }
}
If you call a write command with --mode readonly, the connector returns a structured error with exit code 3 (permission denied).

​
Discovery System

ArgentOS discovers connectors automatically from multiple sources:

​
1. Vendored connectors (tools/aos/)

Shipped with the ArgentOS repository. These are the 61 built-in connectors.

​
2. User connectors (~/.argentos/connectors/)

Installed by the user or downloaded from the marketplace.

​
3. PATH executables

Any binary on your system PATH that starts with aos- is discovered automatically.

​
4. Custom directories

Set ARGENT_CONNECTOR_REPOS environment variable to a comma-separated list of directories to scan.

​
Discovery Process

Each discovered connector gets an installState:
StateMeaning
readyBinary found, capabilities parsed, health check passed
needs-setupBinary works but health check reports missing configuration
repo-onlyConnector directory exists but no runnable binary (needs pip install)
errorBinary exists but capabilities or health probe failed

​
The connector.json Manifest

Every connector has a connector.json file that describes its metadata, commands, auth requirements, and UI field definitions: 
{
  "tool": "aos-github",
  "backend": "github-api",
  "manifest_schema_version": "1.0.0",
  "connector": {
    "label": "GitHub",
    "category": "developer-tools",
    "categories": ["developer-tools", "source-control", "ci-cd"],
    "resources": ["repo", "issue", "pr", "branch"]
  },
  "auth": {
    "kind": "service-key",
    "required": true,
    "service_keys": ["GITHUB_TOKEN"],
    "interactive_setup": [
      "Create a GitHub personal access token with repo scope.",
      "Add GITHUB_TOKEN in API Keys before enabling live reads."
    ]
  },
  "commands": [
    {
      "id": "issue.list",
      "summary": "List issues in a repository",
      "required_mode": "readonly",
      "supports_json": true,
      "resource": "issue",
      "action_class": "read"
    }
  ]
}

​
Security Baseline

All connectors must follow these security rules:
  • No shell execution of unsanitized user input
  • Path-based tools must enforce root allowlist boundaries
  • config show must redact secrets (API keys, tokens, passwords)
  • Error messages must not leak credentials
  • Write operations must respect the permission tier
  • Destructive operations (delete, revoke) require admin mode

​
Integration with ArgentOS

When ArgentOS discovers a connector, it:
  1. Registers it in the connector catalog (src/connectors/catalog.ts)
  2. Makes its commands available as agent tools (src/connectors/tools.ts)
  3. Shows it in the dashboard Systems panel with setup status
  4. Allows it to be used in Workflows as action nodes
  5. Makes it available to the execution worker for autonomous task processing