ait external — Complete Reference

ait external
ait external update
ait external status
ait external doctor
ait external link
ait external unlink

Inspect, diagnose, resolve, pin, materialize, and locally link external Repository dependencies declared by ait-external.toml. Resolution writes an exact ait-external.lock; generated content is materialized below each declaration's repository-relative destination.

Usage: ait external <COMMAND>

Commands:
  update  Resolve and materialize declared external Repositories.
  status  Inspect external pins, links, lock drift, and materialization state.
  doctor  Evaluate external dependency release readiness without repairing it.
  link    Use another local checkout for one declared direct external.
  unlink  Remove one local external override and restore locked content.
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Resolve and materialize declared external Repositories. With no NAME, preserve the manifest's exact pins while reconciling the complete lock DAG. NAME requires exactly one of --to or --latest. --locked is a separate target-free mode that reads an existing drift-free lockfile without changing manifest or lock authority.

Usage: ait external update [--validate] [--no-recursive] [--json]
       ait external update <NAME> (--to <SNAPSHOT> | --latest) [--validate] [--no-recursive] [--json]
       ait external update --locked [--validate] [--no-recursive] [--json]

Arguments:
  [NAME]
          Unique direct external name; requires --to or --latest.

Options:
      --to <SNAPSHOT>
          Pin NAME to this exact immutable Snapshot before resolving and materializing.

      --latest
          Resolve NAME's declared remote and line head, then persist that exact Snapshot pin.

      --locked
          Materialize the existing drift-free ait-external.lock without resolving or changing pins; active local links are rejected.

      --validate
          Stage the selected materialization and binding toolchain probes first; apply it only when validation has no errors.

      --no-recursive
          Materialize direct externals only; the resolved lockfile remains a complete recursive DAG.

      --json
          Emit the complete machine-readable update report.

  -h, --help
          Print help (see a summary with '-h')

Read manifest, lockfile, local-link, binding-path, and generated-materialization facts without repairing or changing them. States include materialized, missing, linked, dirty, and outdated; lock drift is reported separately.

Usage: ait external status [OPTIONS]

Options:
      --json
          Emit the complete machine-readable status report.

  -h, --help
          Print help (see a summary with '-h')

Evaluate manifest, lockfile, materialization, local-link, binding, license, and applicable current-source readiness. The report is always emitted. By default findings are diagnostic only; --fail-on-blocking returns exit code 2 when release_ready is false.

Usage: ait external doctor [OPTIONS]

Options:
      --fail-on-blocking
          Return exit code 2 after emitting the report when release-blocking findings exist.

      --json
          Emit the complete machine-readable readiness report.

  -h, --help
          Print help (see a summary with '-h')

Record a local development override in ait-external.links.toml. NAME must match exactly one direct ait-external.toml declaration. PATH must be an existing directory outside this authoritative Repository; regular updates preserve the override, while locked and release-ready materialization reject active links.

Usage: ait external link [OPTIONS] <NAME> <PATH>

Arguments:
  <NAME>
          Unique direct external name declared by ait-external.toml.

  <PATH>
          Existing local checkout directory; relative paths resolve from the Repository root.

Options:
      --json
          Emit the complete machine-readable link result.

  -h, --help
          Print help (see a summary with '-h')

Remove NAME from ait-external.links.toml. When ait-external.lock exists, restore the matching direct external and its recursive subtree before committing removal of the override. A failed restore leaves the logical link active.

Usage: ait external unlink [OPTIONS] <NAME>

Arguments:
  <NAME>
          Local external override name to remove.

Options:
      --json
          Emit the complete machine-readable unlink and restoration result.

  -h, --help
          Print help (see a summary with '-h')