naas-abi-cli
Command Line Interface (CLI) tool for building and managing ABI (Agentic Brain Infrastructure) projects.
Overview
naas-abi-cli provides a comprehensive set of commands to create, configure, deploy, and interact with ABI projects. It serves as the primary entry point for developers working with the ABI framework, enabling quick project setup, agent interaction, and cloud deployment.
Installation
Install the CLI tool using pip:
pip install naas-abi-cli
Available Commands
Project Management
abi new project <project-name> [project-path] [--with-local-deploy/--without-local-deploy]
Creates a new ABI project with all necessary starter files and dependencies.
What it does:
- Creates a new project directory (must be empty or non-existent)
- Generates project structure with configuration files, Docker setup, and Python package structure
- Generates local deployment scaffolding (
docker-compose.yml,.deploy/, and local.envvalues) by default - Automatically installs required dependencies (
naas-abi-core,naas-abi-marketplace,naas-abi, andnaas-abi-cli) - Customizes project files with your project name
Example:
abi new project my-abi-project
abi new project my-abi-project --without-local-deploy
abi init <path>
Initializes a new ABI project in the specified directory.
Example:
abi init .
Agent Interaction
abi chat [module-name] [agent-name]
Starts an interactive chat session with an AI agent.
Parameters:
module-name: The module containing the agent (default:naas_abi)agent-name: The specific agent class to use (default:AbiAgent)
What it does:
- Loads the ABI engine and specified module
- Launches an interactive terminal chat interface
- Saves conversations to
storage/datastore/interfaces/terminal_agent/
Example:
abi chat naas_abi AbiAgent
abi agent list
Lists all available agents across all loaded modules.
What it does:
- Loads the ABI engine with all configured modules
- Displays a formatted table showing module names and agent class names
Example:
abi agent list
Configuration Management
abi config validate [--configuration-file <path>]
Validates the ABI configuration file for correctness.
Options:
--configuration-file: Path to configuration file (default: usesconfig.yamlfrom current directory)
Example:
abi config validate
abi config validate --configuration-file config.prod.yaml
abi config render [--configuration-file <path>]
Renders the loaded configuration as YAML output, useful for debugging and verification.
Options:
--configuration-file: Path to configuration file (default: usesconfig.yamlfrom current directory)
Example:
abi config render
abi module list
Lists all available modules and their enabled/disabled status.
What it does:
- Loads the engine configuration
- Displays a formatted table showing module names and their enabled status
Example:
abi module list
Deployment
abi deploy naas [-e/--env <environment>]
Deploys your ABI project to Naas cloud infrastructure.
Options:
-e, --env: Environment to use (default:prod). Determines which configuration file to load (e.g.,config.prod.yaml,config.yaml)
What it does:
- Builds a Docker image of your ABI project
- Pushes the image to your Naas container registry
- Creates or updates a space on Naas infrastructure
- Exposes your ABI REST API at
https://{space-name}.default.space.naas.ai
Requirements:
- Naas API key configured in your configuration file
- Docker installed and running
- Deploy section in your
config.yamlfile
Example:
abi deploy naas
abi deploy naas --env prod
Stack Management
Commands for the local Docker Compose stack (config.local.yaml). abi start,
abi stop, and abi logs are also exposed at the top level for convenience.
abi stack snapshot create [-m/--note <text>] [--name <label>]
Takes a point-in-time snapshot of the stack's stateful data so you can roll back later or move the deployment to another host.
What it does:
- Resolves the compose project and its stateful volumes (
postgres_data,minio_data,fuseki_data,qdrant_storage,redis_data,rabbitmq_data,headscale_data); transient volumes (caddy certs, dagster history, caches, the headscale socket dir) are skipped - Gracefully stops the stack so the copy is consistent, archives each volume plus
the host
storage/directory, writes amanifest.json(timestamp, git commit, config fingerprints), then restarts the stack
RabbitMQ note: durable queues only survive a restore if the broker's node name is stable. The compose file pins
hostname: rabbitmqfor this reason.
- Stores everything under
./.snapshots/<id>/(gitignored)
Example:
abi stack snapshot create -m "before v3.15 upgrade"
abi stack snapshot list
Lists snapshots (newest first) with id, date, size, git commit, and note.
abi stack snapshot restore <id> [--yes] [--no-safety-snapshot]
Rolls the stack back to a snapshot. Destructive: it overwrites current data.
What it does:
- Validates the snapshot is complete before touching anything, so a corrupt or partial snapshot aborts without wiping any live data
- Warns if the git commit or
config.local.yaml/.envhave changed since capture - Takes an automatic safety snapshot of the current state first (opt out with
--no-safety-snapshot; skipped automatically on a fresh host with no data yet), so a rollback is itself reversible - Stops the stack, restores the volumes +
storage/, and brings it back up, and if anything fails mid-restore it still brings the stack back up and prints the safety-snapshot id to recover from
Example:
abi stack snapshot restore 20260630-140509
abi stack snapshot delete <id> [--yes] / abi stack snapshot prune [--keep N] [--yes]
Remove a single snapshot, or keep only the newest N (default 5).
abi stack snapshot export <id> <archive.tar.gz> / abi stack snapshot import <archive.tar.gz>
Bundle a snapshot into one portable archive and re-register it on another host : the supported way to migrate a local deployment to a new machine:
# On the source host
abi stack snapshot create -m "migration"
abi stack snapshot export 20260630-140509 abi-migration.tar.gz
# copy abi-migration.tar.gz (and your .env) to the new host, then:
abi stack snapshot import abi-migration.tar.gz
abi stack snapshot restore 20260630-140509
export refuses to overwrite an existing file and import refuses to clobber a
snapshot with the same id; pass --force to either to override. import also
verifies the archive is complete (all volume tarballs + storage present) and
rejects a partial one.
Note: the same
.env(Postgres/MinIO/Fuseki credentials) must be present on the destination host : those credentials are baked into the data being restored.
Nexus admin (workspace / user / org)
Authenticated admin surface against the Nexus HTTP API. Auth via
NEXUS_ACCESS_TOKEN, or NEXUS_EMAIL + NEXUS_PASSWORD. Base URL:
NEXUS_API_URL (default http://localhost:9879).
abi workspace create --name "Research preview" --slug research-preview --org org-...
abi workspace list --org org-...
abi workspace members list --workspace ws-...
abi workspace members add --workspace ws-... --email someone@naas.ai --role member
# Preferred when password signup is off: create-on-invite + OTP/magic-link email
abi user invite --email someone@gmail.com --name "Someone" \
--org org-... --workspace ws-... --role member --workspace-role member
abi org members invite --org org-... --email someone@gmail.com --workspace ws-...
abi user create --email someone@naas.ai --name "Someone" # needs password auth enabled
abi user list --org org-... # or --workspace ws-...
abi org list
abi org members list --org org-...
abi org workspaces --org org-...
All of these accept --dry-run (prints the intended API call) and
--api-url / --token / --auth-email / --auth-password.
Invite endpoints create the user when missing and email OTP / magic-link sign-in.
Credentials: abi user create never prints the password by default. It
writes secrets/NEXUS_USER_<EMAIL>.env (mode 600). Pass --show-password only
when you intentionally need stdout.
Break-glass Postgres (ops VM only, when invite email / browser auth is unavailable):
export NEXUS_POSTGRES_COMPOSE_DIR=/opt/abi
abi user create --via postgres --email someone@naas.ai --name "Someone" --org org-...
abi workspace create --via postgres --name "..." --slug ... --org org-... --owner-id user-...
See issue #1118.
Secret Management
abi secrets naas list
Lists all secrets stored in your Naas workspace.
Options:
--naas-api-key: Naas API key (default:NAAS_API_KEYenvironment variable)--naas-api-url: Naas API URL (default:https://api.naas.ai)
Example:
abi secrets naas list
abi secrets naas push-env-as-base64
Pushes a local .env file to Naas as a base64-encoded secret.
Options:
--naas-api-key: Naas API key (default:NAAS_API_KEYenvironment variable)--naas-api-url: Naas API URL (default:https://api.naas.ai)--naas-secret-name: Name for the secret in Naas (default:abi_secrets)--env-file: Path to the environment file (default:.env.prod)
Example:
abi secrets naas push-env-as-base64 --env-file .env.prod
abi secrets naas get-base64-env
Retrieves a base64-encoded secret from Naas and displays it as environment variables.
Options:
--naas-api-key: Naas API key (default:NAAS_API_KEYenvironment variable)--naas-api-url: Naas API URL (default:https://api.naas.ai)--naas-secret-name: Name of the secret to retrieve (default:abi_secrets)
Example:
abi secrets naas get-base64-env
Script Execution
abi run script <path>
Runs a Python script in the context of a loaded ABI engine.
What it does:
- Loads the ABI engine with all configured modules
- Executes the specified Python script with access to the engine and all loaded modules
Example:
abi run script scripts/my_script.py
Architecture
The CLI is built using:
- Click: For command-line interface framework
- naas-abi-core: Core ABI engine and configuration management
- naas-abi-marketplace: Marketplace modules and agents
- naas-abi: Main ABI package
When run inside an ABI project, the CLI auto-detects the project root and re-runs itself in that project context via uv run --project ....
Project Structure
When you create a new project with abi new project, the CLI:
- Uses template files from
cli/new/templates/project/ - Customizes templates with your project name
- Sets up proper Python package structure
- Sets up local deployment files from
cli/deploy/templates/local/(unless disabled) - Installs all required dependencies via
uv
Integration with ABI Framework
The CLI integrates seamlessly with the ABI ecosystem:
- Engine Loading: Automatically loads modules and agents from your configuration
- Configuration Management: Validates and renders YAML configuration files
- Cloud Deployment: Handles Docker builds and Naas API interactions
- Secret Management: Integrates with Naas secret storage for secure credential management
Dependencies
- Python 3.10+
naas-abi>=1.0.6naas-abi-core[qdrant]>=1.1.2naas-abi-marketplace[ai-chatgpt]>=1.1.0uvpackage manager (for dependency management)
See Also
- ABI Main README - Complete ABI framework documentation
- naas-abi-core - Core engine documentation
- naas-abi-marketplace - Marketplace modules documentation
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file naas_abi_cli-2.16.2.tar.gz.
File metadata
- Download URL: naas_abi_cli-2.16.2.tar.gz
- Upload date:
- Size: 496.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dcd9749927bea34ea24c3e70a8e2c3efebed8e052077096c135ca3721e9272a8
|
|
| MD5 |
18c0541c7d21932cdebcb0f975b4e320
|
|
| BLAKE2b-256 |
d1de98b80c6c94ecb477ae3c7c9949f6a88e2ea853554cd2e2a3f0e51b59aff8
|
Provenance
The following attestation bundles were made for naas_abi_cli-2.16.2.tar.gz:
Publisher:
release.yml on jupyter-naas/abi
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
naas_abi_cli-2.16.2.tar.gz -
Subject digest:
dcd9749927bea34ea24c3e70a8e2c3efebed8e052077096c135ca3721e9272a8 - Sigstore transparency entry: 2366510194
- Sigstore integration time:
-
Permalink:
jupyter-naas/abi@fb47c6520d9fa5d55e3a42eeacce383095be6839 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/jupyter-naas
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fb47c6520d9fa5d55e3a42eeacce383095be6839 -
Trigger Event:
push
-
Statement type:
File details
Details for the file naas_abi_cli-2.16.2-py3-none-any.whl.
File metadata
- Download URL: naas_abi_cli-2.16.2-py3-none-any.whl
- Upload date:
- Size: 202.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
25cca390e9cc2240b3676fd1529054ead68fcfeec54698e98c88aa129d2bc0f9
|
|
| MD5 |
e916e596e1056d59660b4d436eae929e
|
|
| BLAKE2b-256 |
b73af935b2213871a3a50d2143677b23cb837772013ef002f2a8545b294cc68c
|
Provenance
The following attestation bundles were made for naas_abi_cli-2.16.2-py3-none-any.whl:
Publisher:
release.yml on jupyter-naas/abi
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
naas_abi_cli-2.16.2-py3-none-any.whl -
Subject digest:
25cca390e9cc2240b3676fd1529054ead68fcfeec54698e98c88aa129d2bc0f9 - Sigstore transparency entry: 2366510599
- Sigstore integration time:
-
Permalink:
jupyter-naas/abi@fb47c6520d9fa5d55e3a42eeacce383095be6839 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/jupyter-naas
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fb47c6520d9fa5d55e3a42eeacce383095be6839 -
Trigger Event:
push
-
Statement type:
