---
title: "read_library"
description: "Generated reference for the management action read_library: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-library
order: 47
visibility: public
redirects_from: ["/reference/actions/list-library","/reference/actions/read-library-entry"]
---
# read\_library
Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).
A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/read_library`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `tzcloud_read_library`.
**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
## Contract description
List the published code library, or read one entry by `entry`\. Any signed\-in connection can call this\. With no `entry`, each row gives a name, version, content hash, and selection summary\. The full list can be large: narrow it with `contains`, or pass `installed` with `held_only: true`\. With `entry`, read its file list, or pass `file` for that file's content\. Continue a chunked file with `next_offset` as `offset` and its `stamp` until the offset is null; decode base64 where indicated and check the joined content against `sha256`\. `history: true` lists earlier versions and dates, not their files\.
To take the entry, run `download.command_npx` \(`download.command_npx_windows` on Windows\) at your project's root, then follow `download.next`\.
## More about this action
Pass `contains` to get only the entries whose name or summary contains that text, ignoring case\. An entry listed in `installed` is always returned\. Where no entry matches and `held_only` is not true, the result's `note` lists every served entry by name\.
The `installed` argument: The result then gives every entry a standing\. The standing is `current`, `newer`, or `withdrawn` for an entry this list includes, and `not_held` for a served entry the list leaves out, which is compared with nothing\. With `held_only`, only the entries in this list are returned\. Two calls return fewer `not_held` rows: one passing `held_only: true` returns none, and one passing `contains` returns only those its text matches\.
Read one published library entry: its file list with a hash and size per file, or, with `file`, one file's content\. A package's import name is the `name` in its served `package.json`, which resolves to `lib/index.js`, the re\-export of the package's runtime modules\. Its `testing` subpath has the test double, which only an application's tests import\. With no token for `library take`, a signed\-in tool reads each listed file here, the double's `lib/testing.js` among them\. A large file reads in chunks: pass `limit`, then each result's `next_offset` as `offset` with its `stamp` until it is null\. Check the joined content, decoded when `encoding` is `base64`, against `sha256`\. To take the entry, run the result's `download.command_npx`, or `download.command_npx_windows` on Windows, at your project's root, then do what `download.next` says\.
It takes no `version`: it reads the version `read_library` lists, since each publication replaces the library whole\.
The file list has a package's compiled runtime modules under `lib/`, never its source or tests\. Any signed\-in connection can read it\.
Inside a package's copy, the entry's `package.json` is beside its `lib/` folder, kept as a folder, as Use the library's step 5 shows; `npm install` links the copy into `node_modules`, which you never write\.
With `entry` and `history: true`, the result also lists that entry's previously published versions, with the times each was published and superseded\. An inventory read carries no version history\. No call reads an earlier version's files: `previous_versions` gives each one's number and dates, never its files\.
## Access and action metadata
```json
{
"name": "read_library",
"resource": "library",
"tier": "observe",
"surface": "tzcloud",
"access": "anonymous",
"summary": "The library's inventory: catalog rows and their selection summaries, served to any connected identity, and on the wire to a request carrying a credential of an account. With `entry` it reads one entry: One published entry: its file list with a hash and a size per file, or one named file's content, whole or, with `offset`, `limit`, and `stamp`, in chunks on the served context's paging, the stamp the file's hash and a stale one refused context_changed. It is served to any connected identity, and on the wire to a request carrying a credential of an account, like the inventory beside it. A tool reads a package's test double, `lib/testing.js`, here with no token for the take line. Latest only: a publish replaces what is served, and a consumer keeps its own copy of what it holds.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
```
## MCP catalog entry
```json
{
"name": "read_library",
"title": "Read feature library",
"tier": "observe",
"scenario": "API-L0-15",
"summary": "List the published code library, or read one entry by `entry`. Any signed-in connection can call this. With no `entry`, each row gives a name, version, content hash, and selection summary. The full list can be large: narrow it with `contains`, or pass `installed` with `held_only: true`. With `entry`, read its file list, or pass `file` for that file's content. Continue a chunked file with `next_offset` as `offset` and its `stamp` until the offset is null; decode base64 where indicated and check the joined content against `sha256`. `history: true` lists earlier versions and dates, not their files.\n\nTo take the entry, run `download.command_npx` (`download.command_npx_windows` on Windows) at your project's root, then follow `download.next`.",
"owners": [
"API-L0-15",
"LC-06",
"LC-02",
"LC-05",
"CTX-07"
]
}
```
## request
| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object
Additional properties: false
Replaced members: name was replaced by entry |
| /properties/entry | The published entry to read, by the name this call lists\. Leave it out to list the library\. The read takes no `version`: it reads the version this call lists\.
Type: string |
| /properties/file | One file's path within the entry, to read its content; omit it for the file list\.
Type: string |
| /properties/offset | With `file`: a zero\-based Unicode code\-point offset in the file's content as the answer encodes it; defaults to 0\. Pass the previous chunk's next\_offset to continue\. A nonzero offset requires its stamp\.
Type: integer
Minimum: 0
Maximum: 9007199254740991 |
| /properties/limit | With `file`: the most Unicode code points of content this chunk returns, 1 through 16000, default 8000\. Pass offset, limit, or stamp to read the file in chunks; pass none and you read it whole\.
Type: integer
Minimum: 1
Maximum: 16000 |
| /properties/stamp | With `file`: the stamp the previous chunk returned, which is the file's SHA\-256\. Required with a nonzero offset\. A publish that changed the file returns context\_changed; restart at offset 0 without a stamp\.
Type: string
Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /properties/history | Pass `true` to get the entry's `previous_versions`: each earlier version's number and the times it was published and superseded\. Leave it out or pass `false` and you get none\. Over the HTTP route a value other than true or false is refused `invalid_request`\.
Type: boolean |
| /properties/installed | The entries your project already holds, each `{name, version, hash}` from its manifest row, `hash` being the row's `closure_hash`\. The answer then marks each entry `current`, `newer`, or `withdrawn`, and marks `not_held` a served entry this list does not include\.
Type: array |
| /properties/installed/items | Type: object
Required fields: \["name","hash"\]
Additional properties: false |
| /properties/installed/items/properties/name | Type: string |
| /properties/installed/items/properties/version | The version held, as the manifest row records it\.
Type: \["string","null"\] |
| /properties/installed/items/properties/hash | The vendored copy's recorded closure hash, compared with the served closure hash\.
Type: string |
| /properties/held\_only | With `installed`: true returns only the entries in that list, each marked `current`, `newer`, or `withdrawn` and each row whole, and leaves out every `not_held` row\. True without `installed` is refused `invalid_request`\. Defaults to false\.
Type: boolean |
| /properties/contains | Only the entries whose name or summary contains this text, ignoring case, and every entry in `installed`, which is returned whatever the text\. An empty or absent `contains` narrows nothing\.
Type: string
Maximum length: 200 |
## response
| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object
Required fields: \["contract\_version"\]
Additional properties: false |
| /properties/contract\_version | Required value: 1 |
| /properties/entries | Type: array |
| /properties/entries/items | Type: object
Required fields: \["name","kind","closure\_hash"\]
Additional properties: false |
| /properties/entries/items/properties/name | Type: string |
| /properties/entries/items/properties/kind | Type: string |
| /properties/entries/items/properties/version | Type: \["string","null"\] |
| /properties/entries/items/properties/closure\_hash | Type: string |
| /properties/entries/items/properties/summary | Type: \["string","null"\] |
| /properties/entries/items/properties/supersedes | Type: array |
| /properties/entries/items/properties/supersedes/items | Type: string |
| /properties/entries/items/properties/standing | Present when your request passed `installed`\. Standing `current`: the held hash equals the served closure hash\. Standing `newer`: it differs\. Standing `withdrawn`: the held name is no longer served, the row returned from your own item\. Standing `not_held`: the served entry is not in your list and was compared with nothing, and no such row is returned where your request passed `held_only`\.
Allowed values: \["current","newer","withdrawn","not\_held"\] |
| /properties/entry | Type: object
Required fields: \["name","files"\]
Additional properties: false |
| /properties/entry/properties/name | Type: string |
| /properties/entry/properties/kind | Type: string |
| /properties/entry/properties/path | Type: string |
| /properties/entry/properties/version | Type: \["string","null"\] |
| /properties/entry/properties/closure\_hash | Type: string |
| /properties/entry/properties/summary | Type: \["string","null"\] |
| /properties/entry/properties/supersedes | Type: array |
| /properties/entry/properties/supersedes/items | Type: string |
| /properties/entry/properties/published\_at | Type: string |
| /properties/entry/properties/previous\_versions | Under `history: true` alone: each previously published version of this entry with the times it was published and superseded, oldest first\. The list does not carry them\. A versionless entry gains none\. Each gives an earlier version's number and dates, never its files: no call reads an earlier version's files\.
Type: array |
| /properties/entry/properties/previous\_versions/items | Type: object
Required fields: \["version","published\_at","superseded\_at"\]
Additional properties: false |
| /properties/entry/properties/previous\_versions/items/properties/version | Type: \["string","null"\] |
| /properties/entry/properties/previous\_versions/items/properties/published\_at | Type: string |
| /properties/entry/properties/previous\_versions/items/properties/superseded\_at | Type: \["string","null"\] |
| /properties/entry/properties/files | Type: array |
| /properties/entry/properties/files/items | Type: object
Required fields: \["path","sha256","size"\]
Additional properties: false |
| /properties/entry/properties/files/items/properties/path | Type: string |
| /properties/entry/properties/files/items/properties/sha256 | Type: string |
| /properties/entry/properties/files/items/properties/size | Type: integer |
| /properties/file | Type: object
Required fields: \["path","encoding","content","sha256"\]
Additional properties: false |
| /properties/file/properties/path | Type: string |
| /properties/file/properties/encoding | Allowed values: \["utf8","base64"\] |
| /properties/file/properties/content | Type: string |
| /properties/file/properties/sha256 | Type: string |
| /properties/file/properties/stamp | On a chunked read: the stamp to pass with the next chunk, the file's SHA\-256\.
Type: string
Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /properties/file/properties/offset | On a chunked read: this chunk's code\-point offset in the file's content\.
Type: integer
Minimum: 0
Maximum: 9007199254740991 |
| /properties/file/properties/total | On a chunked read: the content's length in code points\.
Type: integer
Minimum: 0
Maximum: 9007199254740991 |
| /properties/file/properties/next\_offset | On a chunked read: the next chunk's offset, null at the last chunk\. Join the chunks' content in order, decode it where the encoding is base64, and check its SHA\-256 against the file's\.
Type: \["integer","null"\]
Minimum: 0
Maximum: 9007199254740991 |
| /properties/download | With the entry answer, on the MCP surface alone\. `command` is the one line that takes the entry with the turnzero command's `library take`, on the origin of the platform that responded\. `command_windows` is the same line for Windows\. Run at the project's root, the line checks every listed file against its SHA\-256 and the entry's closure hash before it writes anything\. It then writes the entry's row in the library folder's `manifest.json` and replaces the entry's folder there whole\. For an entry with compiled modules, it copies `package.json` and `lib/` into the application's folder and runs `npm install`\. Its `next` says where to run the line and which form to run, and hands what remains to the line it prints starting `next:`, which lists for that folder the files to commit and what the application manifest needs\. An entry whose name the line cannot carry gets `next` alone, saying so\.
Type: object
Required fields: \["next"\]
Additional properties: false |
| /properties/download/properties/command | One line, for macOS and Linux: `turnzero library take --entry `, then `--origin ` off `https://turnzero.ai`\. Run it once, as given, at the project's root\. It ends 0 where the entry was taken, 1 where its install failed, and 3 where nothing was written\.
Type: string |
| /properties/download/properties/command\_windows | Present with `command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`\. On Windows, run this one in `command`'s place, as given\.
Type: string |
| /properties/download/properties/command\_npx | The same line run through npx, `npx --no-update-notifier -y turnzero@` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other\. It is present exactly where `command` is\. Run this line first, or `command_npx_windows` on Windows; it runs whether or not the command is installed\. If your safety check refuses it, run `command` where `turnzero --version` responds, else `deploy_files` for a deploy or install the command\. A person or a job may run any of the four forms\.
Type: string |
| /properties/download/properties/command\_npx\_windows | `command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx`\.
Type: string |
| /properties/download/properties/next | Type: string |
| /properties/source\_commit | The library commit this publish was read at\. A project's folder manifest must record, per entry, the commit it was published from; the fact lives on the catalog rather than on any row, so it is returned here or it is unreachable\. Absent before the first publish\.
Type: string |
| /properties/published\_at | When this publish ran, ISO 8601\. Distinct from an entry's own published\_at, which is when that entry last changed\. Absent before the first publish\.
Type: string |
| /properties/note | Present where `contains` matched no served entry's name or summary and `held_only` was not true: one line listing every served entry by name, so a word the library does not use still shows what it serves\.
Type: string |
## Complete payload contract
```json
{
"request": {
"type": "object",
"additionalProperties": false,
"x-renamed": {
"name": "entry"
},
"properties": {
"entry": {
"type": "string",
"description": "The published entry to read, by the name this call lists. Leave it out to list the library. The read takes no `version`: it reads the version this call lists."
},
"file": {
"type": "string",
"description": "One file's path within the entry, to read its content; omit it for the file list."
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "With `file`: a zero-based Unicode code-point offset in the file's content as the answer encodes it; defaults to 0. Pass the previous chunk's next_offset to continue. A nonzero offset requires its stamp."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 16000,
"description": "With `file`: the most Unicode code points of content this chunk returns, 1 through 16000, default 8000. Pass offset, limit, or stamp to read the file in chunks; pass none and you read it whole."
},
"stamp": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "With `file`: the stamp the previous chunk returned, which is the file's SHA-256. Required with a nonzero offset. A publish that changed the file returns context_changed; restart at offset 0 without a stamp."
},
"history": {
"type": "boolean",
"description": "Pass `true` to get the entry's `previous_versions`: each earlier version's number and the times it was published and superseded. Leave it out or pass `false` and you get none. Over the HTTP route a value other than true or false is refused `invalid_request`."
},
"installed": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"hash"
],
"properties": {
"name": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
],
"description": "The version held, as the manifest row records it."
},
"hash": {
"type": "string",
"description": "The vendored copy's recorded closure hash, compared with the served closure hash."
}
},
"additionalProperties": false
},
"description": "The entries your project already holds, each `{name, version, hash}` from its manifest row, `hash` being the row's `closure_hash`. The answer then marks each entry `current`, `newer`, or `withdrawn`, and marks `not_held` a served entry this list does not include."
},
"held_only": {
"type": "boolean",
"description": "With `installed`: true returns only the entries in that list, each marked `current`, `newer`, or `withdrawn` and each row whole, and leaves out every `not_held` row. True without `installed` is refused `invalid_request`. Defaults to false."
},
"contains": {
"type": "string",
"maxLength": 200,
"description": "Only the entries whose name or summary contains this text, ignoring case, and every entry in `installed`, which is returned whatever the text. An empty or absent `contains` narrows nothing."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version"
],
"additionalProperties": false,
"properties": {
"contract_version": {
"const": 1
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"kind",
"closure_hash"
],
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"closure_hash": {
"type": "string"
},
"summary": {
"type": [
"string",
"null"
]
},
"supersedes": {
"type": "array",
"items": {
"type": "string"
}
},
"standing": {
"enum": [
"current",
"newer",
"withdrawn",
"not_held"
],
"description": "Present when your request passed `installed`. Standing `current`: the held hash equals the served closure hash. Standing `newer`: it differs. Standing `withdrawn`: the held name is no longer served, the row returned from your own item. Standing `not_held`: the served entry is not in your list and was compared with nothing, and no such row is returned where your request passed `held_only` (LC-06)."
}
},
"additionalProperties": false
}
},
"entry": {
"type": "object",
"required": [
"name",
"files"
],
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"path": {
"type": "string"
},
"version": {
"type": [
"string",
"null"
]
},
"closure_hash": {
"type": "string"
},
"summary": {
"type": [
"string",
"null"
]
},
"supersedes": {
"type": "array",
"items": {
"type": "string"
}
},
"published_at": {
"type": "string"
},
"previous_versions": {
"type": "array",
"items": {
"type": "object",
"required": [
"version",
"published_at",
"superseded_at"
],
"properties": {
"version": {
"type": [
"string",
"null"
]
},
"published_at": {
"type": "string"
},
"superseded_at": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "Under `history: true` alone: each previously published version of this entry with the times it was published and superseded, oldest first. The list does not carry them. A versionless entry gains none. Each gives an earlier version's number and dates, never its files: no call reads an earlier version's files."
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"sha256",
"size"
],
"properties": {
"path": {
"type": "string"
},
"sha256": {
"type": "string"
},
"size": {
"type": "integer"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"file": {
"type": "object",
"required": [
"path",
"encoding",
"content",
"sha256"
],
"properties": {
"path": {
"type": "string"
},
"encoding": {
"enum": [
"utf8",
"base64"
]
},
"content": {
"type": "string"
},
"sha256": {
"type": "string"
},
"stamp": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "On a chunked read: the stamp to pass with the next chunk, the file's SHA-256."
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "On a chunked read: this chunk's code-point offset in the file's content."
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "On a chunked read: the content's length in code points."
},
"next_offset": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991,
"description": "On a chunked read: the next chunk's offset, null at the last chunk. Join the chunks' content in order, decode it where the encoding is base64, and check its SHA-256 against the file's."
}
},
"additionalProperties": false
},
"download": {
"type": "object",
"description": "With the entry answer, on the MCP surface alone. `command` is the one line that takes the entry with the turnzero command's `library take`, on the origin of the platform that responded. `command_windows` is the same line for Windows. Run at the project's root, the line checks every listed file against its SHA-256 and the entry's closure hash before it writes anything. It then writes the entry's row in the library folder's `manifest.json` and replaces the entry's folder there whole. For an entry with compiled modules, it copies `package.json` and `lib/` into the application's folder and runs `npm install`. Its `next` says where to run the line and which form to run, and hands what remains to the line it prints starting `next:`, which lists for that folder the files to commit and what the application manifest needs. An entry whose name the line cannot carry gets `next` alone, saying so.",
"required": [
"next"
],
"properties": {
"command": {
"type": "string",
"description": "One line, for macOS and Linux: `turnzero library take --entry `, then `--origin ` off `https://turnzero.ai`. Run it once, as given, at the project's root. It ends 0 where the entry was taken, 1 where its install failed, and 3 where nothing was written."
},
"command_windows": {
"type": "string",
"description": "Present with `command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`. On Windows, run this one in `command`'s place, as given."
},
"command_npx": {
"type": "string",
"description": "The same line run through npx, `npx --no-update-notifier -y turnzero@` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other. It is present exactly where `command` is. Run this line first, or `command_npx_windows` on Windows; it runs whether or not the command is installed. If your safety check refuses it, run `command` where `turnzero --version` responds, else `deploy_files` for a deploy or install the command. A person or a job may run any of the four forms (PLD-L0-94)."
},
"command_npx_windows": {
"type": "string",
"description": "`command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
},
"next": {
"type": "string"
}
},
"additionalProperties": false
},
"source_commit": {
"description": "The library commit this publish was read at. A project's folder manifest must record, per entry, the commit it was published from; the fact lives on the catalog rather than on any row, so it is returned here or it is unreachable (LC-07). Absent before the first publish.",
"type": "string"
},
"published_at": {
"description": "When this publish ran, ISO 8601. Distinct from an entry's own published_at, which is when that entry last changed. Absent before the first publish.",
"type": "string"
},
"note": {
"type": "string",
"description": "Present where `contains` matched no served entry's name or summary and `held_only` was not true: one line listing every served entry by name, so a word the library does not use still shows what it serves (LC-06)."
}
}
}
}
```
## Shared contracts
- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)