---
title: Use the library
description: Find a published package or vocabulary, add it to your project with one line, install its code, and update it to a newer version later.
slug: /guides/use-the-library
order: 36
visibility: public
redirects_from: []
---

# Use the library

Prompt:

> This app stores users' documents. Use whatever the platform already provides rather than building it from scratch.

Also works:

- "Is there a ready-made way to do sign-in here, or do I write it?"
- "Bring the storage package into this project."
- "Are the packages we use out of date? Bring them up to date."

Your AI tool finds an entry with `read_library` ([step 1](#1-read-what-is-published)) and takes it into your project with one line, such as `turnzero library take --entry database` ([step 3](#3-add-an-entry-to-the-library-folder)). For a package with code, the line also copies it into `app/lib/<name>/`, and the application installs it from there ([step 5](#5-install-a-package-s-compiled-code)).

This page adds an entry to a project you already have. To start a new service that keeps its data in the database, use [Build a database-backed service](/cloud/getting-started/build-a-database-backed-service/) instead. Its first step is one line that writes the service and takes the [Database](/cloud/backend-packages/database/) package for it. That package is optional, since any PostgreSQL driver reaches the database.

The [notes app](/cloud/concepts/turnzero-command/#the-notes-app-template) is a template that `turnzero scaffold --template notes-app` writes, not a library entry.

Downloading an entry requires a credential. Before running `turnzero library take`, [authorize this computer](/cloud/getting-started/connect-your-tool/#authorize-this-computer-for-deploys) or supply a minted token. Signing your AI tool in to MCP does not authorize the CLI. An AI tool without a shell can read the entry's files over its signed-in MCP connection instead ([step 1](#1-read-what-is-published)).

## What your AI tool does

- Reads the `add-library-entry` [skill](/cloud/concepts/glossary/#skill) (`read_context`, id `skill:add-library-entry`) and follows it.
- Reads the chosen package's page, starting with its Use it when section. Where no entry fits, it tells you so, rather than using a package in a way its contract does not allow.
- Later, when you ask for updates, reads the `update-library` skill (`read_context`, id `skill:update-library`) and follows it.
- Asks you which entry to take where more than one fits. Before an update, it asks you once for each entry. It needs no approval in the browser: the library action only reads, and every write goes to your project.

## What you need

- A project of your own, one your AI tool can write to and save changes in.
- Node.js 24 or later, and npm, on your computer, which run the line and install a package's code ([What your computer needs](/cloud/getting-started/prerequisites/)).
- A token for the CLI: this computer's, set up as [Authorize this computer for deploys](/cloud/getting-started/connect-your-tool/#authorize-this-computer-for-deploys) shows, or a [minted token](/cloud/concepts/glossary/#minted-token) your AI tool sets for the line.
- For a package with compiled code, your application's `package.json`, at `app/package.json` or at the project's root. Where neither file exists, the line makes a minimal `app/package.json` and goes on. It refuses instead where the root holds a `src/` folder or a source file such as `server.mjs`: add that code's `package.json` at the root first.

You can prepare your application's files before signing in. For an ES-module app whose server is `app/server.mjs`, `app/package.json` can start as:

```json
{
  "name": "my-app",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.mjs"
  }
}
```

Keep an existing app's scripts and dependencies. This example has no Turn Zero dependency because no package has been downloaded yet. Leave out `file:lib/...` dependencies while the files they point to are missing.

Once the command is authorized, run `library take` from the project root, the folder containing `app/`. It copies the package, adds its `file:` dependency and runs `npm install` ([step 3](#3-add-an-entry-to-the-library-folder)). For an app kept at the project root, use its existing root `package.json` instead.

## Before your AI starts

**For the AI tool:** Check the following before starting.

- The library action runs under your account's credential. The `library take` command reads this computer's token, which `login` keeps, or a minted token. Without a token, the line sends nothing.
- Where the project uses Turn Zero Team (tzTeam), its registrar connected. The registrar is tzTeam's tool server, and its `validate` with kind `library` verifies the downloaded entry. Without it, `read_library` with `installed` verifies the downloaded entry instead.

## Steps

### 1. Read what is published

`read_library` without `entry` lists every entry with its name, kind, version, content hash, and `summary`. To find one entry, add `contains`, such as `"contains": "storage"`. The response then lists only the entries whose name or summary contains that text, ignoring case. Where no entry contains it and `held_only` is not set, the response's `note` lists every entry the library serves, so a word the library does not use still shows what is there. An entry you name in `installed`, described in step 4, is always listed. Only what it lists can be taken.

`read_library` with `entry` set to an entry's name returns its file list, with each file's hash and size. Add `file` to read one listed path; a large file comes in chunks. A tool with no shell can read each file this way, over MCP, signed in.

Each publication replaces the current library, and older versions are not kept. `read_library` takes no version: it reads the library's current publication. With `entry` and `history: true`, its `previous_versions` gives each earlier version's number and dates, never its files. Your project keeps its committed copy, so a newer publication changes nothing your project contains or has deployed.

### 2. Know what an entry contains

The entry of a [feature package](/cloud/concepts/glossary/#feature-package) contains its product statement `prd.md`, its detailed contract `<name>.md`, and its integration guide `integration.md`. A package with runtime code also contains that code as an npm package, a `lib/` folder and a `package.json` named `@turnzero/<name>`. Eleven packages include code: Account, AI Allowance, Database, Egress, Email, Issue Tracking, Logging, Push, Schedule, Storage, and Turn Zero Mesh.

No `@turnzero` package is published to the npm registry. Download each package only from the library with the `library take` command.

Each of those eleven packages also ships a test double at its `testing` subpath, `@turnzero/<name>/testing`, which only the application's tests import. The two other packages ship none: the platform loads the Node.js Runtime package's code itself, and the Secrets package has no client module.

A [vocabulary](/cloud/concepts/glossary/#vocabulary)'s entry contains its documents and, for the style system, its sheets and its resolver. A font family's entry contains its font files and license. The entry `library/prd` holds the library's own requirements, which the package documents cite. The `add-library-entry` skill says when to take it.

### 3. Add an entry to the library folder

Without a shell, your AI tool can [have Cloud fill a supported runtime package](#put-the-copy-in-a-deploy) from the manifest's `packages` and root `file:` dependency, with no copy in `deploy_files`.

The `add-library-entry` skill takes an entry with one line, which runs the turnzero command's `library take`. Through the Model Context Protocol (MCP), `read_library` with only `entry` returns `download`, which contains the line in four forms. `download.command` is the line for macOS and Linux. `download.command_windows` is the same line for Windows, with `turnzero.cmd` in place of `turnzero`. Your AI tool first runs `download.command_npx`, or `download.command_npx_windows` on Windows. These use npx and need no global turnzero installation. `download.next` says what remains after the line. Where `download.next` says no line takes the entry, the command cannot take it.

No MCP action writes an entry into your project, since a remote server cannot write your AI tool's files. Taking an entry needs a shell that reaches the platform. Where your AI tool's shell cannot reach it, your AI tool asks you to run the line in your own terminal, at your project's root.

For the Database package, the line for macOS and Linux has this form:

```text
turnzero library take --entry database
```

This example shows `download.command`, which runs the installed version. The npx forms name `turnzero@latest` instead. Every form prints the version it runs before taking the entry.

If your AI tool is connected to a platform other than https://turnzero.ai, the returned command includes `--origin` with that platform's address. You do not need to set the address yourself.

Your AI tool first runs `download.command_npx`, or `download.command_npx_windows` on Windows, exactly as returned, at your project's root. That is the folder that contains `system/` or `system.json` beside `app/`, or, on the first download, the folder where the new `system/` is made.

The line reads this computer's token, which `login` keeps, or the minted token your AI tool sets for the line, as the deploy line does.

For example, taking Database into an application with `app/package.json` and no Database dependency writes these two entries. The rows show an example version; the command writes the version the library publishes.

| File | Member | Entry added or updated |
| --- | --- | --- |
| `app/package.json` | `dependencies` | `"@turnzero/database": "file:lib/database"` |
| `app/manifest.json` | `packages` | `{"name": "database", "version": "0.15.0"}` |

The dependency uses `@turnzero/<name>` and a path relative to the folder that holds `package.json`; each `packages` row is the entry's name and version.

[Step 5](#5-install-a-package-s-compiled-code) shows the copied files and the paths for a project whose `package.json` is at the root. [Step 7](#7-the-rows-in-the-manifest-member) explains which manifest the platform reads and when to submit it.

**Without a global installation:** With Node.js and npm installed, you can run `npx --no-update-notifier -y turnzero@latest library take --entry database` from the project root. Use the returned `download.command_npx` or Windows form for your chosen entry, keeping its options. It uses the same credential as the installed command.

**Unattended jobs:** A script or CI job running without an AI coding tool can run the npx line, `npx --no-update-notifier -y turnzero@latest library take --entry <name>`, instead of installing the command. Run it from the project's root with Node.js 24 or later and npm. Set `TURNZERO_CLOUD_MINTED_TOKEN` from the job's secret store, as [Deploying unattended](/cloud/concepts/turnzero-command/#deploying-unattended) describes; no interactive login is needed. The command downloads and writes the whole entry.

**For the AI tool:** Try `download.command_npx` first, or `download.command_npx_windows` on Windows. It works whether or not turnzero is installed globally. If npx can't run here, use the installed form when `turnzero --version` responds. Otherwise, try [installing the command](/cloud/getting-started/prerequisites/#install-the-turnzero-command).

If `npm install -g turnzero` can't run here, use another available route to add the entry to your project. If none works, give the person the exact step you cannot run. A person or a job may use any of the four forms.

For a chat deploying without local package copies, follow [Deploy from a chat](/cloud/getting-started/build-an-app-from-a-chat/). Cloud can fill supported runtime feature packages from the submitted manifest; it does not create a local library folder or download arbitrary entries.

#### Keep the entry whole

The library folder is the project's own `system/`. A project without one can keep a `system.json` file at its root that names a shared folder instead, such as one at the repository's root. The folder it names must exist and lie inside the repository, or the line refuses and writes nothing.

Where the folder holds neither `system/` nor `system.json`, but the folder above it holds one, the line refuses and writes nothing. The folder may be an application's folder inside that project. Run it in the folder above or, where the folder is a project of its own, make an empty `system/` folder in it and run the line again.

The line reads every listed file and checks each one's SHA-256 and the entry's closure hash. The closure hash is one SHA-256 for all the entry's files, so a changed, added or removed file changes it.

It writes nothing until every file is checked. It then writes the entry's row in the library folder's `manifest.json` and each listed file under that folder: under `features/<name>/` for a package, `ui/<name>/` for a vocabulary, and `ui/assets/fonts/<family>/` for a font. Where a read returns HTTP 502, 503, or 504, the line tries it again after 2, then 4, then 8 seconds, at most three more times.

Where a check fails, the line writes nothing and ends with status 3. Run it again to take the entry whole. The [turnzero command reference](/cloud/reference/turnzero-command/#library-take) gives each status of `library take`.

The command refuses, with nothing written, a library folder, an entry's folder, a copy, or the application manifest that is reached through a link leading outside your project. The command also refuses a symbolic link or junction at any path it writes, whatever the link points to. The paths it writes are the library folder's `manifest.json`, the `manifest.json.partial` beside it and beside the application manifest, and the `package.json` it adds the declaration to. They also include the `.take` staging names in the library folder and beside the copy.

If the application manifest is a broken symbolic link or junction, the command refuses and writes nothing.

Four rules apply together for a package with code. Fetch the entry into the library folder, copy its `package.json` and its `lib/` folder, kept as a folder, into `app/lib/<name>/`, and declare it in `app/package.json` as `file:lib/<name>`. Deploy from `app/`, so the zip holds `lib/` at its root and leaves `system/` out. In a project with no `app/` folder, the zip includes `system/` beside `lib/`, and the image build installs from the copies in `lib/`, never from `system/` ([The two project layouts](/cloud/concepts/what-the-deploy-zip-holds/#the-two-project-layouts)). The line follows the first three for you, as step 5 describes.

The line writes every row and every file itself, so your AI tool writes none by hand. Keep every entry whole and unchanged, its documents included. A folder that is missing a listed file, or has changed one, no longer matches its row, and a check reports the entry as moved since the fetch. A tzTeam project also records the version in the package's [instance file](/cloud/concepts/glossary/#instance-file).

Removing a package entry is the exception: your AI tool deletes its row in the library folder's `manifest.json` and its `features/<name>/` folder together by hand ([Author the manifest](/cloud/guides/author-the-manifest/#a-manifest-that-works)). In a tzTeam project, first read the package's integration guide for what removal does to its instance file. A package's removal may require deleting that file or recording consequences in it.

### 4. Check the download

With the tzTeam registrar connected, `validate` with kind `library` hashes the local files and compares them with the manifest.

Without it, call `read_library` with `installed`, one item per manifest row: its `name`, its `version`, and its `closure_hash` passed as `hash`. Add `held_only: true` to return only those entries. The response gives each entry a `standing`:

- `current`: the recorded hash equals the published hash. This confirms the recorded download.
- `newer`: a publication happened after the download. Run the entry's line again, which takes it whole and rewrites its row.
- `withdrawn`: the published library no longer includes the entry. The project keeps using its copy.
- `not_held`: the published library includes an entry your project has not taken.

This call compares recorded hashes and reads no local file, so only `validate` finds a hand edit of a taken file.

### 5. Install a package's compiled code

The application installs the package from its own copy. For a package with compiled code, the line from step 3 copies `system/features/<name>/package.json` and the `system/features/<name>/lib/` folder into `app/lib/<name>/`. On the first download it declares the dependency in `app/package.json` as a path, never a registry name.

```json
"dependencies": {
  "@turnzero/database": "file:lib/database"
}
```

The copy keeps the entry's `lib/` as a folder: `app/lib/<name>/package.json` beside `app/lib/<name>/lib/`, not the files of `lib/` loose in `app/lib/<name>/`. The package's own `package.json` points its name at `lib/index.js` inside the copy, and Node.js finds the package only there, so the copy is laid out like this:

```text
app/
├── package.json
└── lib/
    └── <name>/
        ├── package.json
        └── lib/
            ├── index.js
            └── the rest of the entry's lib/ files
```

The line then runs `npm install` in `app/`, which links the copy into `node_modules`. Never write there yourself. After an install that ends with status 0, the command reads `node_modules/@turnzero/<name>/package.json` through the link.

If that file cannot be read, the command runs `npm install --install-links` once in the same folder and reads again. It prints `installed:` only after a successful install leaves the file readable. If the second install fails or the file remains unreadable, the line ends with status 1; the entry, its row, and the copy stay written. Run the `library take` command again to download the whole entry. A failed first install starts no second install.

Where your project already declares the copy at another `file:` path, the line replaces the copy at that path and leaves the declaration as it is. Commit the copy, `app/package.json`, and its lockfile beside your code. In a project with no `app/` folder and a `package.json` at its root, the line uses `lib/<name>/` and that root `package.json`. Where the `package.json` is at the project's root and the project also has an `app/` folder, the copy is `app/lib/<name>/`, declared `file:app/lib/<name>`.

Where neither place has a `package.json`, the line makes `app/package.json` with only what the install needs. That is `"private": true`, a `name` made from your project folder's name, `"type": "module"` where the package's own `package.json` declares it, and the dependency, with no scripts. It prints one `made:` line that says so, and goes on as above. To start a whole new service instead, the [`scaffold` line](/cloud/concepts/turnzero-command/#starting-a-new-service) writes the application and takes the entry. `npm install` receives neither `TURNZERO_CLOUD_MINTED_TOKEN` nor `TURNZERO_CLOUD_UPLOAD_GRANT`.

The line prints one line after its `reading:` line and before it writes, saying the application goes in `app/` and why. Where the root holds a `src/` folder or a source file such as `server.mjs` and no `package.json`, it refuses and writes nothing. It names what it found and the two ways on: add the `package.json` at the root, or move that code into `app/`.

If you downloaded a package before scaffolding, `scaffold` refuses the nonempty `app/` folder and gives recovery commands. Check that the folder contains only generated files before deleting it. Then scaffold and download any packages the template does not include.

Where the install fails, the line ends with status 1, and the entry, its row, and the copy stay written. It ends the same way where the application manifest's `packages` member could not be written. Run `npm install` in `app/`, or run the line again. In Windows PowerShell, run npm as [What your computer needs](/cloud/getting-started/prerequisites/#windows-powershell) describes.

Import the package by the `name` in its `package.json`, for example `import { applyMigrations } from '@turnzero/database'`, and the test double from the `testing` subpath. The modules are ES modules. An application in CommonJS scope loads them with `import()`. The Account package's type declarations import Node.js types, so an application that checks its types installs `@types/node`.

After taking and installing Account, a CommonJS file, `account-client.cjs`, can load its client like this:

```js
async function createAccountClient(options) {
  const { makeVerifyClient } = await import('@turnzero/account');
  return makeVerifyClient(options);
}

module.exports = { createAccountClient };
```

Call `await createAccountClient(options)` from an async function. The [Account client](/cloud/backend-packages/account/#the-client) lists the options, including the required `baseUrl`.

#### Put the copy in a deploy

After taking the package, keep its copy and the `file:` dependency together. For Account in an `app/` project, `app/package.json` declares `"@turnzero/account": "file:lib/account"`. The copy holds `app/lib/account/package.json` beside `app/lib/account/lib/`, including its compiled files. Submit the application manifest with the package's name and version before deploying ([step 7](#7-the-rows-in-the-manifest-member)).

Choose the route you are using:

- **The turnzero command:** run `turnzero deploy` from the folder containing the application's `package.json`, normally `app/`. The command includes the copy under `lib/account/`. Keep that path out of `.deployignore`; `turnzero hash --list` lets you check the files the zip will hold.
- **A file list with `deploy_files`:** send the copy's files, or omit the whole copy so the platform can fill it. To fill it, the list's top `package.json` must declare the `file:` dependency, and the submitted manifest's `packages` row must name `account` at the version the library currently serves. List no path at or under the copy's declared path. If you send any part of the copy, send all its files: the platform fills none of that copy. Keep your local copy committed even when you omit it from this deploy.
- **A zip for the upload route:** include the copy yourself; this route does not fill it. With `package.json` at the zip's root, the Account copy is `lib/account/package.json` beside `lib/account/lib/`. Zip the contents of `app/`, not the `app/` folder around them. [Deploy from your computer](/cloud/getting-started/deploy-an-application/#3-build-and-upload-the-artifact) gives the upload steps.

A library copy Cloud fills needs no entry in `package-lock.json`; without a shell, write no lockfile for it. Send a lockfile npm already wrote unchanged.

Other packages use their own entry name in place of `account`. For a project with no `app/` folder, deploy from the root containing `package.json` and `lib/`; the zip includes its `system/` folder too. The image build installs from the declared copies, never from `system/` ([The two project layouts](/cloud/concepts/what-the-deploy-zip-holds/#the-two-project-layouts)).

### 6. Take a newer version

The `update-library` skill compares each entry your project keeps with the published library through `read_library` with `installed`, and asks you before updating each one. For each entry you accept, it runs the entry's line from step 3 again, which replaces the entry whole and, for a package with code, its copy. It then opens `features/<name>/<name>.md` in the project's library folder (normally `system/`). It follows that document's Lifecycle, Migration, and Removal section's entries above your old version, moves the instance file's pin, and checks the update as step 4 describes.

### 7. The rows in the manifest member

The application manifest is `app/manifest.json` where `app/` holds `package.json`, as in a scaffolded project, and otherwise `manifest.json` beside a `package.json` at the project's root. Where it exists, the `library take` line rewrites its `packages` member from the rows of `system/manifest.json` after each download. Each entry holds the row's `name` and `version` and nothing else, and the line's `packages:` line says it wrote them.

If the manifest does not exist, the command creates a [minimal manifest](/cloud/getting-started/deploy-an-application/#2-declare-the-manifest) with the package rows, no services, and a public audience. Add the services and audience your application needs before submitting it.

The command rewrites the whole manifest as two-space JSON, so read it again before editing. Preserve `packages` when changing other fields, then submit the updated manifest before deploying.

The platform uses the submitted manifest, not `system/manifest.json`. A deploy reports mismatches between `packages` and the ZIP's library copies in `manifest_notice`. Without a folder manifest, enter the `packages` names and versions by hand from `read_library`; `deploy_files` checks them against the served library when filling omitted runtime packages. [Deploy from a chat](/cloud/getting-started/build-an-app-from-a-chat/) gives that route.

A row of `system/manifest.json`, and the entry of `packages` copied from it:

```text
system/manifest.json  {"name": "database", "version": "0.15.0", "closure_hash": "…", "source_commit": "…", "fetched_at": "…"}
manifest packages     {"name": "database", "version": "0.15.0"}
```

## Expected result

The line first prints a `reading:` line naming the entry, its version, and its count of files. Where it makes `app/package.json`, the line saying the application goes in `app/` comes next.

The command prints `taken:` and, for a package with code, `copied:` and `installed:`. It prints `made:` if it created `app/package.json`. The `packages:` line reports the manifest update or tells you to copy the rows if it could not write them. A successful run exits with status 0. After the download, the project contains:

- the entry's files under `system/features/<name>/`;
- its row in `system/manifest.json`;
- for a package with code, `app/lib/<name>/`, with the `file:` dependency declared and linked into `node_modules`;
- where none existed, the application manifest, made with the rows and the other members of the smallest manifest.

`validate` with kind `library` finds the folder equal to its manifest, or `read_library` with `installed` returns `current` for the row. Your AI tool reports the entry, its version, the files it wrote, and the import name.

## Refusals

See the [refusals reference](/cloud/reference/refusals/) for other platform errors.

A `standing` of `newer`, `withdrawn`, or `not_held` is a normal result, not a refusal. The line's own statuses are on the [turnzero command reference](/cloud/reference/turnzero-command/#library-take).

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `invalid_request` | 400 | `file`, `offset`, `limit`, `stamp`, or `history` was given without `entry`; `entry` was empty or not text; or an entry read included `installed`, `held_only`, or `contains`. | Give `entry` for an entry read. Leave it out for an inventory read, which alone accepts `installed`, `held_only`, and `contains`. |
| `invalid_request` | 400 | An entry read gave `offset`, `limit`, or `stamp` without `file`, or a `history` value other than true or false. | Give a listed file path with chunk arguments. Give `history` as true or false, or leave it out. |
| `invalid_request` | 400 | An inventory read gave `held_only: true` without `installed`, a non-boolean `held_only`, or a `contains` that is not text or is over 200 characters. | Pass `installed` beside `held_only: true`. Give `held_only` as true or false, and `contains` as a short piece of text. |
| `context_changed` | 409 | A publication changed the file between two chunks of one read. | Read the file again from offset 0 without a stamp. |
| `no_such_entry` | 404 | `read_library` named an entry the published library does not include, or a `file` not in the entry's file list. | Take the name from `read_library` and the path from the file list, then call again; where the refusal gives the entry's path for your file, use that. A withdrawn entry stays usable from your project's copy. |

## Related

- Each package's page, such as [Account](/cloud/backend-packages/account/), describes the package for a reader. Where versions differ, `read_library` is correct.
- [The manifest](/cloud/concepts/the-manifest/) describes the `packages` member step 7 fills.
- [The turnzero command](/cloud/concepts/turnzero-command/) describes `library take`, which the line runs.
- [read_library](/cloud/reference/actions/read-library/) gives the action's arguments and result.
