loomcli 0.6.0rc2

Weave — the Powerloom CLI. Declarative manifests (apply/plan/destroy) + resource inspection, validated against the authoritative JSON Schema published in this repo.

loomcli

Schema language + CLI for Powerloom — the Terraform-like declarative framework for Claude Managed Agents.

This repo is the source of truth for the Powerloom manifest schema (apiVersion: powerloom.app/v1) and the weave command-line tool that authors + applies manifests against a Powerloom control plane.

• PyPI: loomcli
• Binary: weave (console script installed by pip)
• Repo: github.com/shanerlevy-debug/loomcli
• Platform it orchestrates: github.com/shanerlevy-debug/Powerloom

Install

pip install loomcli
weave --version

For other install paths (single binary, from source), see the Powerloom monorepo's docs/install-weave.md.

Why loom + weave (naming)

The platform is Powerloom. The CLI tool is Loom (the PyPI wheel + Python module + git repo name), and its console script is weave (what Loom does). Mirrors the kubectl / Kubernetes pattern: platform name distinct from tool name, tool name distinct from command you type.

Layout

.
├── loomcli/             # Python package (Typer CLI)
│   ├── cli.py           # app root
│   ├── auth.py          # login + token persistence
│   ├── client.py        # HTTP client against Powerloom REST
│   ├── commands/        # subcommands: apply, plan, get, workflow, agent-session, ...
│   └── manifest/        # parser, planner, applier, jsonschema validator
├── schema/
│   └── v1/              # authoritative JSON Schema
│       ├── powerloom-dialect.schema.json   # meta-schema defining x-powerloom-* keywords
│       ├── dialect-docs.md                 # narrative docs for each dialect extension
│       ├── powerloom.v1.bundle.json        # assembled multi-kind bundle
│       └── kinds/                          # one JSON Schema per manifest kind
├── examples/
│   └── minimal/         # one minimal valid manifest per kind
├── tests/
│   ├── test_*.py        # CLI tests (47+)
│   └── schema/          # schema tests — parse + validate + cross-refs (5)
├── pyproject.toml
├── loomcli.spec         # PyInstaller spec (single-binary build)
├── build-binary.sh
├── LICENSE              # Elastic License v2 (ELv2)
├── CHANGELOG.md
└── .github/workflows/
    └── publish.yml      # PyPI OIDC trusted publish (tag triggered)

Quickstart — author + apply a manifest

weave auth login --dev-as [e-mail]   # local dev

cat > agent.yaml <<'EOF'
apiVersion: powerloom/v1
kind: OU
metadata:
  name: engineering
  parent_ou_path: /dev-org
spec:
  display_name: Engineering
---
apiVersion: powerloom/v1
kind: Agent
metadata:
  ou_path: /dev-org/engineering
  name: code-reviewer
spec:
  display_name: Code Reviewer
  model: claude-sonnet-4-6
  system_prompt: "Review Python code for bugs and style."
  owner_principal_ref: user:[e-mail]
  skills: [python-lint]
EOF

weave plan agent.yaml       # show what apply would do (Terraform-style diff)
weave apply agent.yaml      # apply; prompts for confirmation
weave get agents --ou /dev-org/engineering

Supported kind: values

Kind	Metadata	Notes
OU	name, parent_ou_path	Root OUs omit parent_ou_path.
Group	name, ou_path
GroupMembership	group_path, member_ref	member_ref: user:<email> or group:<path>
RoleBinding	principal_ref, role, scope_ou_path, decision_type	decision_type is allow or deny
Skill	name, ou_path	current_version_id on spec must be pre-uploaded via REST.
MCPServerRegistration	name, ou_path	BYO — pre-existing URL.
MCPDeployment	name, ou_path	14+ templates (files / postgres / slack / github / notion / jira / ...).
Agent	name, ou_path	skills and mcp_servers on spec expand to AgentSkill/AgentMCPServer resources.
AgentSkill	agent_path, skill_path	Usually implicit via Agent.skills.
AgentMCPServer	agent_path, mcp_registration_path	Usually implicit via Agent.mcp_servers.
Credential	agent_path, mcp_registration_path	Bearer minted server-side; no secret material in YAML.
SkillAccessGrant	skill_path, principal_ref	Additive allowlist beyond OU-scoped RBAC.
Workflow	name, ou_path	Phase-14 feature.

Commands

weave plan manifest.yaml              # show what apply would do
weave apply manifest.yaml             # apply; prompts for confirmation
weave apply -y ./manifests/           # directory + auto-approve
weave destroy manifest.yaml           # reverse-order teardown
weave get agents --ou /dev-org/engineering
weave get mcp-deployments -o json
weave describe agent /dev-org/engineering/code-reviewer
weave import agent /dev-org/engineering/code-reviewer > agent.yaml
weave auth whoami
weave workflow apply workflow.yaml
weave workflow run my-workflow --inputs scope=example
weave workflow status <run-id>
weave agent-session register --scope "<slug>" --summary "<one-line>"
weave agent-session ls --status active

Global flags:

--api-url URL       Override POWERLOOM_API_BASE_URL
--config-dir PATH   Override POWERLOOM_HOME
--version           Print CLI version and exit

Schema as source of truth

Manifests are validated at CLI runtime against schema/v1/. The same schema is consumed by:

1. Powerloom server-side Pydantic — reads the schema and generates typed request/response models (planned upstream adoption; today hand-maintained with a drift detector).
2. IDE yaml-language-server — `# yaml-language-server: $schema=...` headers on example manifests under examples/ enable inline validation in VSCode / JetBrains / vim-lsp.
3. LLM-authored manifests — any Claude session handed the schema + dialect docs can produce correct manifests first-try.

Using a single source for all four paths makes drift impossible by construction.

Industry-standard pattern: kubectl, Helm, Argo, and Flux all validate user-submitted manifests against a published JSON Schema (or CRD) at runtime. Pydantic / struct-tag validation is an implementation detail downstream of the wire-format schema.

Dialect extensions

Beyond vanilla JSON Schema Draft 2020-12, Powerloom defines x-powerloom-* keywords that carry control-plane semantics:

• x-powerloom-server-populated — field is populated by the server, not the author.
• x-powerloom-immutable — field set at create, immutable thereafter.
• x-powerloom-reconciler — reconciler behavior hints.
• x-powerloom-ref — cross-kind reference (e.g. Agent → Skill).
• x-powerloom-tier-gate — minimum tier required for the feature.

Full reference: schema/v1/dialect-docs.md.

Versioning

• Schema: semver git tags schema-v1.x.y. Breaking changes bump the major; additive changes bump the minor; docs-only or wording-only changes bump the patch.
• CLI (PyPI): semver git tags vX.Y.Z on this repo. Trigger PyPI publish. Track CLI version with weave --version.
• Per-kind: optional kind: Agent/v2 qualifier lets individual kinds evolve independently inside a major.

The Powerloom monorepo pins this repo's schema to a specific version via pip install loomcli==<version> in its dev dependencies (no git submodule).

Development

git clone https://github.com/shanerlevy-debug/loomcli.git
cd loomcli
pip install -e ".[dev]"
pytest                    # 47 CLI + 5 schema tests
weave --version

Build the single binary

./build-binary.sh         # -> dist/weave (or weave.exe on Windows)
./dist/weave --version

PyInstaller produces a platform-native single-file binary with the JSON Schema bundled inside — no Python required on the target machine. Cross-platform matrix (Linux / macOS / Windows / arm64) is tracked in the Powerloom monorepo's docs/loomcli-overhaul.md M1.b.

Release workflow

Publish to PyPI on tag push:

# 1. Bump version in pyproject.toml (X.Y.Z semver).
# 2. Commit + push.
# 3. Tag and push:
git tag v0.4.0
git push origin v0.4.0

The .github/workflows/publish.yml workflow runs preflight (tag matches pyproject version, schema bundle present), builds wheel + sdist, smoke-tests the wheel (install + weave --version + --help), verifies the schema is inside the wheel, then publishes to PyPI via OIDC Trusted Publishing (no API token).

Optional TestPyPI dry-run:

gh workflow run publish.yml -f target=testpypi

License

Elastic License v2 (ELv2). See LICENSE.

Intentional gaps

• No weave edit (in-place kubectl-style editor). Post-Phase-13.
• No weave logs <session-id> --follow (WebSocket tail). Post-Phase-13.
• No bulk export (weave export --all). Per-resource import only.
• Local skill-archive upload via manifest (local_archive: ./skill.tar.gz) not supported — upload via REST first, reference the resulting current_version_id by UUID.
• OIDC device-code login is stubbed; dev-mode impersonation is the working login path until Phase 9 ships in Powerloom.
• Cross-platform binary matrix not yet wired — build on your host OS for now.
• Server-side Pydantic codegen from this schema not yet adopted in the Powerloom monorepo (drift-detector covers the hand-maintained case).