Skip to content

CLI Overview

asactl is the CLI used with ASAHub and OpenASA agreements.

Positioning

  • asactl is the CLI client for ASA agreements.
  • It supports both built-in module commands and top-level agreement call.
  • It is designed for mixed local workspace and remote service usage.

Relationship to the docs

Item Primary concern
OpenASA documentation standards, runtime, API contracts
ASAHub documentation Hub product usage and resource workflows
asactl local workspace and remote Hub operations

Core Concepts

  • ASA: Agent Service Agreement
  • asactl: a command-line runtime that lets users or agents inspect agreements, query services, and invoke agreement-defined actions.

Architecture Layers

  1. route: CLI entry and argument parsing
  2. driver: call assembly and transport execution
  3. invoke: unified invocation model
  4. payload (NDJSON): external envelope format
  5. transport adapter: CLI / HTTP / HTTPS / WS
  6. modules: account / service / agreement / flow / plugin / build / store / oss
  7. call: top-level agreement invocation command

Entry Points

asactl [module] [subcommand] [flags]
asactl call <agreement> -a <action> [flags]

Modules and Aliases

  • account (acc)
  • service (svc)
  • flow
  • agreement (pt)
  • plugin (plg)
  • build
  • store
  • oss

Environment Variables

Variable Description Default
ASACTL_SERVER_HOST Remote ASAHub service URL https://api.asahub.ai
ASACTL_USER_DIR Local user data directory <HOME>/.asactl/user
ASACTL_WORKSPACE_DIR Local workspace root <HOME>/.asactl
ASACTL_REMOTE_TIMEOUT_MS Remote request timeout in milliseconds 10000
ASACTL_DEV Development mode switch disabled
ASACTL_INSECURE_TLS Skip TLS certificate verification for remote call disabled

ASACTL_USER_DIR and ASACTL_WORKSPACE_DIR also accept ~, $HOME, and %USERPROFILE% style prefixes.

Note on ASACTL_SERVER_HOST:

  • https://api.asahub.ai is the default remote entry for CTL
  • for local development, override it explicitly, for example http://127.0.0.1:3000

Command Style

  • The current primary command names from ctl are used here.
  • When an alias exists, the long form is preferred.
  • Agreement versions are written with the v prefix, for example v1.0.0.

See CLI Installation, CLI Usage, Command Matrix, and Agreement Call.