---
title: "una.ita/1"
url: https://una-lang.org/en/docs/agents/schemas/una.ita-1/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# una.ita/1

`una.ita/1` is a JSON document of the Agent ABI, defined in `spec/30 §6`. This page gathers what the specification says about it at v0.4.0: each section whole where it opens with the document, and otherwise the parts that name it.

## Commands

From `spec/30 §6`, in full.

With `--json`, each command of `una ita` prints one `una.ita/1` document (rule 1). `una --json ita lock` of a package whose `ita.una` adds the path dependency `util` (§12 rule 6) prints:

```json
{
  "schema": "una.ita/1",
  "command": "lock",
  "written": ["ita.lock"],
  "changes": [
    {
      "change": "add",
      "package": "util",
      "origin": "path deps/util",
      "version_from": null,
      "version_to": "0.2.0",
      "digest_from": null,
      "digest_to": "sha256:628a11aacf38c392c3224401a087d357fbee26abf719488dfdaec055872f1764",
      "ceiling_from": "",
      "ceiling_to": "",
      "trusted_from": [],
      "trusted_to": [],
      "consented_from": null,
      "consented_to": null,
      "authority": []
    }
  ],
  "diagnostics": [],
  "error": null
}
```

1. **`una ita`.** The package manager is the command `una ita` of the `una` binary. The same binary invoked under the name `ita` (its `argv[0]` basename, `ita` or `ita.exe`) behaves as `una ita`: `ita lock` is `una ita lock`. With `--json`, each command prints one document, `una.ita/1`: `schema` first, then `command`, `written` (the files it wrote) and `diagnostics`; a command that resolves (`lock`, `update`, `add`, `remove`) also gives `changes`, the review of §10 rule 8, after `written`, and `error` last, the reason it failed outside its diagnostics, such as a file it could not write, or `null`, and `tree` gives `root` and `packages` in place of `written` (§12 rule 9). The exit code is 1 when a diagnostic is an error, and 2 for a usage error, such as a directory without `ita.una`.
2. **Commands of this release.** `una ita lock [--check [--fresh]] [--dry-run] [--accept-authority <package>]… [--accept-trust <package>@<digest>]… [--accept-key <package>]… [path]` (§4 rule 4, §10 rules 7 and 8, §12 rule 6, §13 rule 2, §14 rule 8); `una ita update [<name>…] [--cooldown <hours>] [--now] [--dry-run] [--accept-authority <package>]… [--accept-trust <package>@<digest>]… [--accept-key <package>]…` and `una ita add <name> [<version>] [--as <local>] [--from <source>] [--now] [--dry-run]`, on the package in the current directory (§10 rules 9 and 10); `una ita tree [path]` and `una ita remove <name> [path]` (§12 rule 9); `una ita fetch [path]` (§14 rule 9); `una ita vendor [path]` (§9 rule 8); `una ita verify [path]` (§10 rule 11); `una ita publish [path]`, `una ita yank <version> [path]`, `una ita audit [path]`, `una ita watch <owner> [<name>…] [--from <source>]`, `una ita bundle <file> [path]` and `una ita unbundle <file> [path]` (§15). `una ita key` joins later.
3. **No network, no other program.** No command of this release opens a network connection: a registry is read from a local mirror directory (§14 rule 1), a submission to an `https://` source stops before anything is sent (§15 rule 1), and a bundle goes through a file. Itá never starts another program.

## Package content, digest and archive

From `spec/30 §9`, the parts that name this schema.

8. **Vendoring.** `una ita vendor [path]` copies each registry package of the lock from Itaoca into `vendor/ita/<source>/<release>/` of the package at `path`, `.` by default, where `<release>` is `<owner>+<name>-<version>`, or `<name>-<version>` for a name without an owner, with its provenance beside it in `vendor/ita/<source>/<release>.provenance`. The copy is written from the verified bytes of Itaoca's copy (rule 6) into a fresh private directory as rule 5 writes, with its files writable, renamed into place, and loaded as every command loads it (rule 9); the provenance is written the same way, as one file. A symbolic link at `vendor`, `vendor/ita` or `vendor/ita/<source>` refuses the copy (U7010), and nothing is written through it. A copy already there that verifies is kept; one whose files verify and whose provenance is missing or does not verify takes Itaoca's provenance; one whose files do not verify is U7010 and is left as it is. A package Itaoca does not hold is U7011. Path dependencies are not copied: they are read from their directory. An invalid `ita.una` or `ita.lock` is reported and nothing is written. With `--json` it prints one `una.ita/1` document whose `written` lists the directories and files written, relative to the package.

## Versions and resolution

From `spec/30 §10`, the parts that name this schema.

8. **The review and consent** (ADR 0122 rule 25). Before a command writes a lock that differs from the one it replaces, it prints one line per package added, changed or dropped, compared by name and origin: `add util 0.2.0 (path deps/util): digest sha256:…; may Console[print]; uses Console[print]`, with `old -> new` for a version, digest or ceiling that changed, `; trust keys; consented sha256:…` after it for a package with trusted modules before or after, with `old -> new` too, and `drop util 0.2.0 (path deps/util)`. A change of the trusted modules or of the consented digest alone is a change. `uses` is what the package's code uses in the new graph, checked at tier 0: the union of the `uses` of its functions and handlers. With `--json`, each line is an entry of `changes`: `change` (`add`, `change` or `drop`), `package`, `origin`, `version_from`, `version_to`, `digest_from`, `digest_to`, `ceiling_from`, `ceiling_to`, `trusted_from`, `trusted_to`, `consented_from`, `consented_to` and `authority`. Each consent flag names what it accepts, and nothing else: a ceiling wider than the one the lock records for the package, matched by name and origin, needs `--accept-authority <package>` (U7009), and a trust that no recorded consent covers for the package's content as it is now needs `--accept-trust <package>@<digest>`, with the content digest of that content (U7012); a consent to another digest is refused and says so. Both flags repeat, one per package. A bare `--accept-authority`, an `--accept-trust` without a digest, an `--accept-authority` naming a package that no need of `ita.una` names, an `--accept-trust` naming one that neither a need nor a trust line of `ita.una` names, and two `--accept-trust` flags of one package with different digests are usage errors. When consent to a ceiling or a trust is missing, the review is printed all the same, `--dry-run` or not, followed by `to accept, after reviewing: una ita <command> <flags>` with the exact flags to copy, and the command refuses with the diagnostics and writes nothing. A file that cannot be written exits with code 1, and an internal error (U8001) with code 3; with `--json` each prints one `una.ita/1` document whose `error` is the message, `null` otherwise. `una ita add` and `una ita remove` take neither flag: their refusals are repaired by `una ita lock` with it.

## Path dependencies in the program

From `spec/30 §12`, the parts that name this schema.

9. **`una ita tree [path]`** checks the program at tier 0 and prints the root's name and version, then one line per dependency, in the form of the report's human line; with `--json`, one `una.ita/1` document with `schema`, `command` (`"tree"`), `root`, `packages`, the report's `dependencies`, and `diagnostics`. **`una ita remove <name> [path]`** removes the need of `name` from `ita.una`, with its indented lines, and the `needs` section when it empties, edited on the text as read, `\r\n` as `\n`; then resolves as `una ita lock` does and, only when the resolution succeeds, writes the lock and then `ita.una`, each through a temporary file and a rename, putting the lock back when `ita.una` cannot be written. A name the root does not need, or an `ita.una` that does not parse, is a usage error and nothing is written. Neither opens a connection.
