CLI reference¶

weaver [--version] command ...

Run weaver <command> --help for the exact options in the installed version. This page records command responsibility, shared interaction and status semantics, and the selection grammar that differs between commands. Machine-readable output records the current JSON documents.

Commands¶

Command	Purpose
`session`	Run lifecycle commands in one persistent Session.
`workflow NAME`	Run a named sequence from `workflow.yml` in one Session.
`initialise`	Create or adopt named Fabric items and write a project. The `initialize` spelling is also accepted.
`doctor`	Check authentication and Fabric connectivity for a named workspace without reading a project.
`check [PROJECT_FOLDER]`	Parse and validate a project without contacting Fabric.
`build [SOURCE]`	Build project structure into selected logical items and install it, unless bundle-only mode is selected.
`install BUNDLE`	Install a previously built bundle directory or `.weaver.zip` archive.
`load [ITEM ...]`	Run installed loadable objects for the selected logical items.
`test [ITEM ...]`	Run installed Tests and Assumptions for the selected logical items.
`health`	Report load, test and build health for installed items.
`wipe [TARGET ...]`	Empty physical source items/reset semantic definitions, with the settled catalogue disposition.
`unbind TARGET ...`	Remove catalogue claims without changing physical items.
`mirror`	Fork another catalogue's installed estate into the current workspace's catalogue.
`fabric environment publish`	Publish Weaver into a Fabric Environment.
`fabric notebook push`	Create or update a Fabric notebook definition.
`fabric notebook run`	Run a deployed Fabric notebook.
`fabric capacity`	Resume, suspend or report a Fabric capacity.

Workspace options¶

Lifecycle commands accept the applicable subset of:

--workspace NAME
--workspace-config PATH
--catalogue Warehouse/Name
--environment Environment
--environment Workspace/Environment

Explicit command-line values override values from workspace configuration. If no workspace was otherwise supplied, project commands look for workspace-config.yml in the current directory. A workspace inherited from weaver session takes precedence over that file.

A typical configuration is:

workspace: Parcel Development
environment: Weaver
catalogue: Warehouse/Catalogue

targets:
  Lakehouse/Landing: Landing_Dev
  Warehouse/Operations:
    name: Operations_Dev

workspace is the only required key. targets may be absent. Build reads configured/explicit bindings. Catalogue-backed Load/Test/Health read installed bindings; catalogue-free refresh and source/file Test use configured targets or logical names. See workspace configuration for execution.build, execution.run and source mappings.

Item and target selection¶

The nouns are deliberate:

An item is a logical identity such as Warehouse/Operations.
A target is a physical Fabric item such as Warehouse/Operations_Dev.

Build selects logical items with a repeatable option because its positional argument is the source:

weaver build ./parcel-ops \
  --item Lakehouse/Landing \
  --item Warehouse/Operations=Warehouse/Operations_Dev

ITEM=TARGET supplies or overrides the physical binding. The two sides must have the same kind. Naming no --item builds every configured item.

Load and test select logical items positionally. In catalogue mode naming none selects installed items (Reports excluded). Catalogue-free Load requires explicit semantic models/project selectors; catalogue-free Test reads project validations:

weaver load Lakehouse/Landing Warehouse/Operations
weaver test Warehouse/Operations
weaver load

Health uses repeatable --item options. Wipe selects physical targets positionally:

weaver health --item Warehouse/Operations
weaver wipe Warehouse/Operations_Dev --dry-run

Interaction and automation¶

--non-interactive means the invocation must not wait for input, offer retry prompts or open browser sign-in. It does not approve destructive work.

--yes authorises an action that would otherwise require confirmation. An unattended destructive command needs both:

weaver wipe Warehouse/Operations_Dev \
  --workspace "Parcel Development" \
  --non-interactive \
  --yes

Commands that accept --json emit one JSON document to stdout and do not prompt. Output fields and version guarantees are command-specific; do not infer a stable schema from one example.

Build and install¶

The normal build plans and installs in one command:

weaver build

For a split handoff, retain the bundle and install it later:

weaver build \
  --bundle-only \
  --bundle-path ./dist/parcel-bundle

weaver install ./dist/parcel-bundle

Installation executes the bundle in its frozen workspace/targets/runtime without reopening source or replanning. build --dry-run presents read-only changes without retaining a bundle; suitable existing targets are required. Build/Load/Test accept --concurrency N as a total invocation cap in addition to configured resource limits. Type/PowerBI project selectors are defined in Shared selection.

Load, test and health selection¶

load --name is repeatable whole-name case-insensitive regex selection. Without --ancestors/--descendants expansion it skips dependency ordering. Both recursive directions start from original seeds and stay within requested items. In a Lakehouse, qualify ambiguous names as Tables/Schema.Object or Files/Schema.Object; a Warehouse uses Schema.Object.

load --stale selects objects whose load health is not Green. --as-of changes its freshness cutoff and is valid only with --stale. --reload reconstructs each selected table and cannot be combined with --stale. --dry-run reports the plan without running it.

Test accepts repeated regex --name and repeated --file paths/directories/globs, which may be combined. Files force source mode without installation/recording; no catalogue also selects source mode. --source supplies project context. Targeted runs collect diagnostics. See Test selection.

health --as-of DATETIME changes the freshness instant; it must include a time zone. --no-inventory skips the physical inventory check for certified objects. Health exits 0 for Green and 1 for Amber or Red.

Destructive commands¶

wipe --dry-run displays the settled plan. Named source targets plus a resolved catalogue normally empty both the targets and that catalogue; --unbind keeps the catalogue but still empties targets. Semantic-only named Wipe retains the catalogue, resets model definitions and removes claims. Reports cannot Wipe. Standalone unbind removes only claims, leaving all physical items unchanged. Unscoped Wipe uses recorded installations only when configuration still binds those same targets. See Wipe behaviour.

mirror also empties destination items. Inspect its plan and require --yes for unattended execution. The source catalogue is read before Weaver changes the destination, and the settled plan names the destination items it will empty.

Shared CLI behaviour¶

The Weaver CLI parses one command, applies one interaction policy and reports one command outcome. Command-specific arguments are listed on the command pages, and current result fields are in Machine-readable output.

Parsing and help¶

The command parser owns command names, positional arguments, options, mutually exclusive choices and required values. Parsing completes before a command handler runs. An unknown command or option, a missing required value or an invalid parser-level combination is rejected without starting the requested operation.

A bare weaver invocation prints top-level help and performs no operation. --help and command help print the parser's current usage and options and complete successfully. Parser usage errors are written as parser diagnostics and complete with a non-success status. Exact option sets and generated synopsis text are documented on each command's Reference page.

Workflow and Session entries use the same command parser as standalone invocations. A workflow parses every entry before its first operation. The interactive Session keeps running after help, a usage error or a command failure.

Interactive and non-interactive input¶

An invocation can prompt only when input is an interactive terminal and --non-interactive is absent. Piped input is not treated as an operator available for an unexpected confirmation.

--non-interactive is an input policy. It prevents stdin questions, single-key retry waits and browser sign-in. Required input or authorisation that is missing under that policy is an error. It does not select credentials and does not grant permission to mutate anything.

Some interactive source commands offer an edit-and-retry choice after a supported source error. Non-interactive and JSON invocations make one attempt. Commands that do not define a retry loop do not acquire one merely because a terminal is present.

weaver session is itself interactive and does not take --non-interactive. When its input is a non-terminal stream, it reads ordinary command lines until end-of-file; it does not turn nested commands into implicitly authorised operations.

Destructive authorisation¶

--yes grants the command-specific authorisation that would otherwise be requested. It does not make the invocation non-interactive, choose a workspace, authenticate, suppress a plan or repair invalid input.

A destructive command settles and displays the scope it will change before asking for confirmation. Declining an available prompt changes nothing. When a prompt is unavailable, authorisation is refused unless the command received --yes. An unattended destructive invocation therefore needs both --non-interactive and --yes.

A confirmed Workflow authorises its displayed sequence once. Nested commands receive that authorisation and do not ask again. --non-interactive propagates into every Workflow entry and can only make the entry's input policy stricter.

Only commands that expose an authorisation boundary accept --yes. Its absence on another command is not a dry-run guarantee; use that command's documented execution mode.

Human output and machine output¶

In human mode, normal command results and requested reports are written to stdout. Errors and progress belong to stderr. Terminal colour and symbols may improve presentation but are not the only carrier of status.

For a command that supports --json, stdout contains one JSON result or failure document after parsing succeeds. Prompts are not allowed to contaminate that document; a required authorisation becomes a JSON failure unless it was supplied. Progress remains on stderr or is suppressed. Parser help and parser errors occur before this JSON boundary and retain parser output semantics.

JSON is a rendering mode, not approval, non-interactive credentials or a compatibility promise. The exact current fields, nesting and format versions belong to the command and Python result Reference pages. A command that always returns a machine document, or exposes no --json, is identified on its own Reference page.

Status and exit semantics¶

A successful completed command returns a success process status. A rejected request, failed operation, unsuccessful report or missing required authorisation returns a non-success status. Argument parsing errors are parser failures rather than operation reports.

Report-bearing commands decide success from the report's semantics. For example, an unsuccessful Load or Test report is non-success even when the report itself was rendered completely. Health is successful only for a Green report. A command that submits asynchronous work can succeed when the documented submission boundary succeeds; that status does not assert a later remote outcome.

Interactive cancellation before execution is not universally a failure. A Workflow declined at its available confirmation, and setup cancelled before it changes state, complete without claiming that work ran. Destructive commands define their own cancellation status in Reference; callers should distinguish “nothing ran” from “the requested operation succeeded”.

Test/Health non-success findings continue through a Workflow and cause final exit 1; other non-success statuses or raised Weaver errors stop it immediately. Earlier effects remain. An interactive Session instead returns to its prompt after a failed command; the process eventually exits successfully through exit, quit or end-of-file rather than using an earlier command failure as its final status.

Interruption¶

At an interactive Session prompt, Ctrl-C abandons the current input and presents a clean prompt. During a Session command, interruption stops that command, reports interrupted and keeps the Session open. A pasted multiline entry stops after its first interrupted or failed command.

The source retry prompt treats Ctrl-C, end-of-file and Escape as declining the retry while preserving the original failure.

Standalone commands do not define a separate cross-platform signal-to-status contract here. An interrupt can stop the process and leave the operation at its documented partial-state boundary. Automation must use the operation's idempotence and recovery contract rather than assuming interruption rolls work back or emits a final JSON document.

Defined behaviour¶

Across commands, Weaver:

completes parser validation before invoking a command handler;
prints help without running an operation and rejects usage errors as parser failures;
prompts only on an interactive input stream when interaction is permitted;
treats --non-interactive as input suppression and --yes as separate authorisation;
keeps human results on stdout and errors or progress on stderr;
emits one stdout JSON document after successful parsing when a command's JSON mode applies;
derives success or failure from the command or report semantics rather than from rendering completion;
continues Workflow Test/Health findings but stops execution failures, while keeping an interactive Session alive after command failures; and
handles prompt and Session interruption as described without promising rollback or a universal standalone signal status.

See Workflow behaviour, Session and runtime behaviour, and Health behaviour for operation-specific boundaries.