Build a company CLI

Use ProjectCLI to expose your installed packs through a company-owned executable. It uses the same planning API available to custom interfaces.

Register the entrypoint

cli.py

from harnest.authoring import ProjectCLI
from acme_agent_pack.pack import pack

cli = ProjectCLI(name="acme-agent", packs=[pack])

def main() -> int:
    return cli.run()

pyproject.toml

[project.scripts]
acme-agent = "acme_agent_pack.cli:main"

The packs order is the execution order. Their names must be unique. Install the Harnest executable alongside the company CLI, or select it explicitly:

cli = ProjectCLI(
    name="acme-agent",
    packs=[pack],
    harnest_command=("/approved/path/harnest",),
)

Pin that executable and the Python Harnest package to the same release. Initialization uses the executable’s scaffold; upgrades use the Python migration engine.

Commands and flags

Command	Default behavior	Additional flags
`init DIRECTORY`	Plan and apply to an absent or empty directory.	`--dry-run`, `--framework adk\|langgraph`, `--minimal`, `--template`, `--template-sha256`, `--json`, pack options.
`upgrade DIRECTORY`	Print a read-only combined plan.	`--apply`, `--json`, pack options.

acme-agent init support-bot --team customer-success --dry-run --json
acme-agent init support-bot --team customer-success
acme-agent upgrade support-bot
acme-agent upgrade support-bot --apply

A later --apply command builds a fresh plan; the CLI does not persist and replay an earlier preview. --json prints a plan without file contents or option values. It can be combined with application flags and does not itself make the command read-only.

Exit code	Meaning
`0`	Success, including a plan with no changes.
`1`	Operational error.
`2`	Blocked plan or invalid command-line arguments.

Initialize from a template

Pass a Harnest template to your team’s CLI:

acme-agent init ./sales --template acme-sales --team sales

--template accepts the same template project name, short slug, or HTTPS wheel URL as harnest init. For an HTTPS wheel, optionally pin its contents:

acme-agent init ./sales \
  --template https://packages.example.com/acme_sales.whl \
  --template-sha256 "$TEMPLATE_SHA256" \
  --team sales

The planner calls harnest init with those template options in a temporary staging directory, then runs the pack initializers against the resulting files. The template supplies the initial agent structure, instructions, skills, framework, and mode. Packs apply their project customizations afterward. Existing pack ownership and write policies still govern conflicts. --template cannot be combined with an explicit --framework or --minimal. --template-sha256 requires --template. Without a template, the framework still defaults to ADK. Use --dry-run to review the combined template and pack changes before creating the project. Planning can download the template; it does not modify the requested destination. A template download or validation failure prevents pack hooks from running and leaves that destination unchanged.

Typed pack options

Declare a Pydantic options model when creating the pack. String, integer, and number fields become typed flags. Enums become choices; defaults and validation remain in the Pydantic model.

Model input	CLI example
String	`--team customer-success`
Integer	`--replicas 2`
Enum	`--environment production`
Boolean	`--enabled true`
List or object	`--regions '["eu-west", "us-east"]'`

Use explicit JSON literals for booleans and structured inputs. Avoid field names reserved by the CLI, such as framework, minimal, template, template_sha256, json, and apply. With multiple packs, flags gain the pack name prefix: --acme-team, --platform-region. Underscores in field names become hyphens in flags. Options are validated before that pack’s callbacks execute and are not stored in harnest-packs.lock. During upgrades, a pack receives context.options = None unless its options were supplied; read persisted company choices from its configuration file.

Add a company command

add_command returns an argparse.ArgumentParser. Add your arguments and return an integer exit code from the handler:

import argparse
from pathlib import Path

def inspect_company_file(arguments: argparse.Namespace) -> int:
    path = arguments.directory / "acme-agent.yaml"
    print(f"Company configuration: {path}")
    return 0 if path.is_file() else 1

parser = cli.add_command(
    "inspect-company", inspect_company_file,
    help="Locate this agent's company configuration",
)
parser.add_argument("directory", type=Path)

Custom handlers own their work and error handling; they do not automatically participate in the project transaction. Other Harnest commands are not automatically forwarded. To expose them, register an explicit company handler. cli.run(arguments, stdout=..., stderr=...) supports embedded callers and tests. It returns an exit code for normal command execution; argparse retains its usual exit behavior for help and invalid arguments.

Overview

Get started

Guides

Build a company CLI

Register the entrypoint

Commands and flags

Initialize from a template

Typed pack options

Add a company command

​Register the entrypoint

​Commands and flags

​Initialize from a template

​Typed pack options

​Add a company command

Register the entrypoint

Commands and flags

Initialize from a template

Typed pack options

Add a company command