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, restore, and locally link external Repository dependencies declared by ait-external.toml. Resolution writes an exact ait-external.lock; generated content is placed at each repository-relative destination declared in the manifest.

Usage: ait external <COMMAND>

Commands:
  update  Resolve and restore declared external Repositories.
  status  Inspect external pins, links, lock drift, and restored content.
  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 restore declared external Repositories. With no NAME, preserve the manifest's exact pins while updating the complete dependency lock. NAME requires exactly one of --to or --latest. --locked is a separate target-free mode that reads an existing drift-free lockfile without changing the manifest or lockfile.

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 restoring its files.

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

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

      --validate
          Prepare the selected files and run destination toolchain checks first; install them only when validation has no errors.

      --no-recursive
          Restore direct external dependencies only; the resolved lockfile still records the complete dependency graph.

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

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

Read the manifest, lockfile, local links, destination paths, and generated content without repairing or changing them. The report explains whether content is present, missing, linked, dirty, or 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')

Check the manifest, lockfile, restored content, local links, destination bindings, licenses, 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 the current Repository; regular updates preserve the override, while locked restores and release checks 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')