XGIC CLI

The thin modular framework behind every xgic command—one brand for humans and AI agents.

Namespace: xgic.cli · Console entry: xgic · Brand: XGIC CLI only (ADR-0005)

Standards hub: xgic/ai · README standards

Vision

XGIC products share a single CLI brand (xgic) with a thin core and domain modules. This repository is the core only: argument parsing, plugin loading, environment detection, and output helpers. Payload, Dev Container lifecycle, and GitLab ops live in separate packages so each module can version, test, and publish independently.

Humans get a stable xgic --help surface. AI agents (including Grok Build) get the same map in AGENTS.md—no inventing Make targets or host-global tooling.

Why this package exists

Ecosystem

Architecture: ADR-0005.

Quick start

Install (PyPI)

uv pip install xgic-cli
xgic --help
xgic --version
xgic info

Development (editable)

uv pip install -e ".[dev]"
xgic --help

Typical stack install

uv pip install \
  "xgic-cli>=0.2.0" \
  "xgic-dev-cli>=0.2.0" \
  "xgic-payload-cms-cli>=0.2.0"
xgic up --help
xgic payload --help

Console commands (core)

Domain packages register additional subcommands via entry point group xgic.cli.commands.

Library API (core only)

from xgic.cli.core import EnvironmentContext, EnvironmentType
from xgic.cli.utils.output import print_info, print_error
from xgic.cli.app import CommandContext, build_parser, main

Plugin entry points

[project.entry-points."xgic.cli.commands"]
my_module = "my_package.cli:register"

def register(subparsers):
    p = subparsers.add_parser("example", help="...")
    p.set_defaults(func=run_example)

Handlers may accept a CommandContext or (args, env=...).

AI agent guidance

• Prefer xgic over ad-hoc scripts for environment and product ops.
• Install core + needed domain modules; do not reimplement lifecycle in the app repo.
• Destructive or credential-regenerating flows belong in domain modules with explicit confirmation.
• Follow hub public-safe rules for any public GitHub issue/PR text.

Status and publishing

0.2.2 — errors. An unexpected error includes the exception type. MemoryError no longer prints a blank message.

0.2.1 — usage. xgic with no arguments prints usage only (no architecture epilogue). Domain modules still ship separately.

0.2.0 — thin core. Framework + environment detection + output helpers.

Publishing to PyPI: follow python-package-release.md (TestPyPI RC + smoke → PyPI via OIDC Trusted Publishing; uv build/smoke). Tags: vX.Y.ZrcN → TestPyPI; vX.Y.Z → PyPI. Requires GitHub Environments testpypi / pypi and matching Trusted Publishers on the index. The release milestone is titled X.Y.Z, matching the published version. Set it on every issue and pull request in that release. GitHub does not copy the issue milestone onto the pull request. The candidate and the final publish share it. Work tracking.

Requirements

• Python 3.14+

License

Apache License 2.0. See LICENSE and NOTICE.
Copyright form: Copyright 2026 XGIC.