manpage.txt

AIXCL(1)                          User Commands                          AIXCL(1)

NAME
       aixcl - AI & Infrastructure Stack Control CLI

SYNOPSIS
       aixcl <command> [subcommand] [options]
       aixcl restart [service]

DESCRIPTION
       aixcl is a unified command-line tool for managing AI services, monitoring
       stack, and models. It provides a Docker-native workflow for
       running LLMs locally and orchestrating AI services.

       AIXCL follows a governance model that separates Runtime Core (always
       enabled) from Operational Services (profile-dependent). See
       docs/architecture/governance/ for architectural documentation.

COMMANDS
       stack start [--profile|-p <profile>]
              Start all services. Uses PROFILE from .env file if set, otherwise
              shows available profiles. Use --profile or -p to specify a profile explicitly.

       stack stop
              Stop all services

       stack restart [--profile|-p <profile>] [service1] [service2] ...
              Restart the entire stack or specific services. With no service names,
              uses PROFILE from .env file if set, otherwise --profile is required.
              With service names (e.g. ollama), restarts only those
              services; profile is not required.

       stack status
              Show service status

       stack logs [svc] [n]
              Show logs for all services (last 100 lines then follow), or for one
              service with optional line count n (default 50, range 1-10000),
              then follow. Use 'engine' as svc to see logs for the active
              inference engine (ollama).

        stack init
               Generate .env file, admin credentials, and Vault secrets (one-time).

       restart [service]
              Shorthand for 'stack restart [service]'.

       service <start|stop|restart> <name>
              Control individual service

              Runtime Core Services (always enabled):
              $INFERENCE_ENGINE (e.g., ollama)

              Operational Services (profile-dependent):
              open-webui, postgres, pgadmin, prometheus, grafana,
              cadvisor, node-exporter, postgres-exporter, nvidia-gpu-exporter,
              loki

              Note: OpenCode is a VS Code plugin, not a containerized service.

       models <add|remove|list> [name ...]
              Manage LLM models

              add     Add one or more models (e.g. models add a b c)
              remove  Remove one or more models
              list    List installed models

       engine <set|auto> [engine]
               Configure the active inference engine.

               set     Manually assign an engine (ollama)
               auto    Auto-detect optimal engine based on hardware

       utils check-env
              Validate environment setup

        utils bash-completion
               Install bash completion for aixcl and ./aixcl. Enables tab
               completion for all commands, subcommands, and flags. Run once
               after initial setup; new shell sessions pick it up automatically.
               To activate in the current shell:
                 source ~/.local/share/bash-completion/completions/aixcl

        utils prune
               Remove volumes and state files, keep images for fast restart.

        utils prune --all
               Full removal of all AIXCL resources and configuration. Requires
               typing 'PURGE' at the confirmation prompt. Removes: containers,
               images, volumes, networks, state files, project directories
               (logs/, .security/, .audit/), AIXCL Podman configuration
               (~/.config/containers/), NVIDIA CDI user config, and bash
               completion files. Intentionally preserves /etc/subuid,
               /etc/subgid, ~/.local/share/containers/, and podman.socket as
               these are standard system config shared with other tools.
               The system remains fully operational after this command.
               To also reset Podman storage: podman system reset --force

        checks {all|paths|agents|elisions|generated|ascii|yaml|compose|env|pr-refs <file>}
               Run local CI parity checks. 'all' runs every check, continues
               on failure, prints a summary table, and exits non-zero if any
               check failed. Individual actions front the corresponding
               scripts in scripts/checks/.

        test {all|command|workflow|lib|apps|security} [--quick|--dry-run]
               Run the platform test suites. 'all' runs every suite including
               the security tests. --quick skips slow model-download tests;
               --dry-run previews discovery without executing.

        release {prep|tag|finish|status}
               Release process mechanics. 'prep' drafts the changelog and
               creates the release issue and branch, stopping at the GPG
               commit. 'tag' tags the merged release on the canonical remote
               and verifies publication. 'finish' syncs main back into dev
               and cleans up. 'status' shows the current release cycle state.
               GPG commits and merge decisions always remain with the human
               operator.

        help
               Show help message

EXAMPLES
       Start the entire stack:
              aixcl stack start --profile sys
              # Or set PROFILE=sys in .env file, then:
              aixcl stack start

       Restart a single service:
              aixcl service restart postgres

       Restart specific stack services (no profile needed):
              aixcl stack restart ollama

       Add a new LLM model:
              aixcl models add phi3


       Check environment requirements:
              aixcl utils check-env

ENVIRONMENT
       AIXCL uses environment variables from .env file (auto-created from
       .env.example on first run). Key variables include:

       PROFILE
               Default profile for stack commands (bld, sys).
              Set this to avoid specifying --profile on every command.

       INFERENCE_ENGINE
              The core backend running inference. Default: ollama.
              Supported options: ollama.

       POSTGRES_USER
              PostgreSQL username

       POSTGRES_PASSWORD
              PostgreSQL password

       POSTGRES_DATABASE
              PostgreSQL database name


FILES
       .env (in project directory)
              Main configuration file (automatically created in the same
              directory as the aixcl script, typically the repository root).
              Not ~/.env.

       .env.example (in project directory)
              Template configuration file

       .env.local (in project directory)
              Local overrides (optional, ignored by git)

ARCHITECTURE
       AIXCL separates services into two categories:

       Runtime Core (Strict)
              Always enabled, required for AIXCL to function:
              - Inference Engine: LLM inference engine (Ollama)
              - OpenCode: VS Code plugin for IDE integration

       Operational Services (Guided)
              Profile-dependent, support/observe the runtime:
              - Persistence: postgres, pgadmin
               - Observability: prometheus, grafana, loki, cadvisor,
                 node-exporter, postgres-exporter, nvidia-gpu-exporter
              - UI: open-webui

       See docs/architecture/governance/ for complete architectural documentation.

SEE ALSO
       docker(1), docker-compose(1), ollama(1)

AUTHOR
       AIXCL Project

BUGS
       Report bugs at https://github.com/xencon/aixcl/issues

AIXCL                            2024                             AIXCL(1)