---
title: What the turnzero command reads and prints
description: Look up what each turnzero line reads beside its credential and every line it prints, beyond the common case.
slug: /concepts/what-the-turnzero-command-reads-and-prints
order: 21
visibility: public
redirects_from: [/concepts/the-turnzero-commands-options-and-output, /concepts/the-turnzero-cloud-commands-options-and-output]
---

# What the turnzero command reads and prints

What the turnzero command reads and prints is the reference half of [The turnzero command](/concepts/turnzero-command): what each line reads beside its credential, and what it prints. The command's page gives the common case: the lines your tool runs, a deploy from call to outcome, and the four statuses. [How the turnzero command finds its credential](/concepts/how-the-turnzero-command-finds-its-credential) says which credential each line reads. The [turnzero command reference](/reference/turnzero-command) gives each subcommand's usage line, its options, and the statuses it ends with.

## What it reads

The credential each line reads is [How the turnzero command finds its credential](/concepts/how-the-turnzero-command-finds-its-credential)'s. The command also reads:

- **Your application's folder.** The folder must contain `package.json` at its top, and that folder becomes the zip's root. [What the deploy zip holds](/concepts/what-the-deploy-zip-holds) says what the zip leaves out and the limits a deploy checks. The command stops at a symbolic link it would otherwise include, and reports it, because the build would not follow it. It also stops at a folder whose zip would contain more than 65,535 files.
- **The zip it builds.** The same folder always zips to the same bytes, and a `.zip` file named with `--path` is uploaded as it is. Every version of the command builds the same zip from the same folder on the same Node.js version, so a hash printed by one version matches the upload of another.
- **Your application's Git commit.** Where the folder that `deploy` zips is inside a Git repository, the command reads the commit checked out there from Git's own files, with no `git` program needed. It sends that commit with the start, and the platform keeps it with the version it deploys. The commit is sent as it is, without changes you have not committed. Where no commit can be read, or `--path` names a `.zip` file, the command sends none. `hash` reads no commit.
- **The files you name.** `secret` reads the file `--value-file` names. `put` reads the file `--path` names, whole. `provision` and `run` read the environment file. `library take` reads the library folder, its `manifest.json`, and your application's `package.json`.
- **`TURNZERO_DEPLOY_NO_WAIT`.** Where this environment variable has any value, the command returns once the deploy has started, and `read_status` shows the outcome.
- **`TURNZERO_CLOUD_USER_AGENT`.** Where this environment variable is set, its value is added to the user agent the command sends, `turnzero/<version>`, so your own records can tell your runs apart. The value takes printable characters only, and any other character ends the command with status 3 before any request, under every subcommand that sends one.

### The line's options

The [turnzero command reference](/reference/turnzero-command) gives every option each subcommand takes, what it sets, and what holds where it is absent. A subcommand is one word, and one named for a thing takes its action first, as `secret store` and `library take` do. Every other value is a named option, written `--name value` or `--name=value`. An unknown subcommand, action, or option ends the command with status 3, and the printed sentence lists what the command takes.

Under every subcommand that takes `--origin`, its value is an `https` address with no path, or an `http` address on your own machine. Its host has only letters, digits, dots, and hyphens, or is an IPv6 address in brackets.

An option's value that opens and closes with a double-quote character is read without that pair, because a shell on Windows can leave the quotes in place. A path you write into a line has none of `&`, `|`, `<`, `>`, and `^`. PowerShell passes a path that has no space to `npx.cmd` without its quotes, and `cmd` then reads those characters as command syntax. A line that a tool call returns has no such path, because the call refuses one.

On Windows, the command refuses a path under `--path`, `--value-file`, or `--env-file` that still contains a double quote, since no Windows path contains one. The usual cause is a quoted path that ends with a backslash, which cmd and Windows PowerShell 5.1 read as keeping the quote. Write the path with no backslash at its end. On macOS and Linux the command takes the path as given.

Under `secret`, a `--value-variable` that names a variable the command reads its own credential from, `TURNZERO_CLOUD_MINTED_TOKEN` or `TURNZERO_CLOUD_UPLOAD_GRANT`, written in any case, is refused, as [Supply a secret value without exposing it](/guides/supply-a-secret-value-without-exposing-it) says.

`--version` prints the command's version, and `--help` prints its usage. Each is read only as an argument of its own: as an option's value, such as `--path --help`, it is that value.

### The environment file

`provision` writes the environment file, `.env` in the folder it runs in or the file `--env-file` names, and `run` reads it.

The command writes the file whole under another name beside it, `.env.turnzero-cloud-writing` for `.env`, and renames that file into place, so a run that fails leaves `.env` as it was. A deploy leaves that file out, as it leaves out `.env`. The command tries the write before it re-mints anything, so a file it cannot write ends the run with status 3 while the credentials are still valid. It removes the file beside `.env` where the run ends before the rename, and where an interrupt ends the run.

`provision` prints each credential setting as a count of characters, never as a value, and makes each re-mint once, because the first request may have reached the platform.

The command reads the file by these forms, and no other:

- `NAME=value`. The name is a letter or an underscore, then letters, digits, and underscores. Spaces and tabs before the name and around the `=` are dropped, and so is the word `export` before the name.
- A comment: a line whose first character after any spaces and tabs is `#`.
- An empty line, or one that holds spaces and tabs alone.

The file is UTF-8 text. A byte-order mark at its head and a carriage return before a line's end are dropped. A name set on two lines takes the later line's value. A line of another form, or a folder with no `package.json`, ends the run with status 3 before anything starts. A file that is not there is read as no settings.

A value is everything after the first `=` to the end of its line, with the spaces and tabs at its two ends dropped. One pair of matching quotes, `"` or `'`, around the whole value is dropped. Nothing else in a value is interpreted, so a `#` after a value is part of the value.

## What it prints

The command prints plain lines. `hash` prints `sha256:` followed by the hash in 64 lower-case hexadecimal characters on its first line:

```text
sha256: <64 hexadecimal characters>
```

For a folder with nothing more to report, and without `--list`, that is its only line. After it, `hash` prints up to four more lines, each only where it applies:

- `left out:` with the paths the zip left out, each relative to the folder, a folder with a closing slash. The line lists at most ten paths, in order, and then the count of the rest.
- `warning:` with the name of each `.zip` file at the top of the folder. The upload includes such a file, so keep a build's zip outside the folder unless your application reads it.
- `warning:` with the name of each file in the zip that looks like a key or a credential. The upload includes such a file. Where one holds a secret, move it out of your application's folder before the next deploy, and store a value your application needs with `store_secret`, as [Store a secret](/getting-started/store-a-secret) describes. The line lists at most ten names, in order, and then the count of the rest.
- `warning:` with the health path of `manifest.json`, where no other file in the zip contains the path's last part, in its text or in its own path, such as `/health` for `/api/health`. The path `/` draws no warning, and a path longer than 80 characters is printed cut short. A deploy waits for that path to return 200, so check that your application serves it. The command cannot see a route built in another form, so this line is a warning and never a refusal. The platform refuses a first deploy on a narrower reading, as [Author the manifest](/guides/author-the-manifest#choosing-the-health-path) describes.

None of these lines changes the status or the zip. A name in them has each character you would not see, such as a line ending, replaced by a percent escape. A name longer than 80 characters is cut short, and the health path is printed without its query. For the health path, the command sets aside package files and documentation, as the platform's own reading does.

A file looks like a key or a credential where one of three things holds, whatever the case of its name and wherever it stands in the folder:

- Its name is `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, `.netrc`, `.pgpass`, `.htpasswd`, or `credentials.json`, or it starts with `client_secret` and ends `.json`.
- Its name ends `.key`, `.p8`, `.p12`, `.pfx`, `.jks`, `.keystore`, `.ppk`, or `.env`.
- It holds a private key written as text, under any name. Such a key starts with a line of five hyphens, the word BEGIN, sometimes the kind of key, and the words PRIVATE KEY. A file that only mentions that first line, such as a page of documentation, is not named.

The line never shows what a file holds. A `.pem` file that holds only a certificate is not named, and a file that holds a whole key as an example is.

With `--list`, `hash` then prints one line for each file the zip holds, in the zip's order: `file:`, the file's size in bytes, and its name, whole. In the name, each character you would not see is replaced by a percent escape. `hash` reads no grant and sends nothing, so `hash --list` is the preview of what a deploy from the folder would upload.

`deploy` prints these lines, in this order:

- `zip:` with the number of files and bytes zipped from the folder, or the `.zip` file uploaded as it is, then `sha256:` and the zip's hash, the same hash `hash` prints;
- `files:` with the folder's top-level entries the zip holds, at most ten and then the count of the rest, each folder with a closing slash. It closes with a reminder that `hash --list` names every file, so a stray file at the folder's root is seen before the upload. A `.zip` file named by `--path` prints no such line;
- the `left out:` line and the `warning:` lines, as `hash` prints them, each only where it applies;
- `prepared:` with the upload's identifier, the environment the deploy goes to, and when its grant expires, before the upload starts, so the identifier ties the deploy to your run;
- where the response says the environment runs no version yet and no file of the zip names the manifest's health path, the platform's own refusal. It opens `No source text in the zip names the health path`. Then comes `Nothing was uploaded and nothing was started.`, and the command ends with status 3;
- `uploaded:` with the bytes uploaded under the grant and the upload's identifier;
- `started:` with the platform's response to the start, on one line, which includes `health_path`, the manifest's health path the check probes, so a wrong path shows before the image build ends;
- then, as the deploy's progress arrives, one line for each step the deploy enters, such as `step: image_build at 0s`;
- `waiting:` with the seconds since the last progress line, printed after each progress read that adds no line once twenty-five seconds have passed. So a silent build prints a line about every half minute while it still runs;
- one line with the outcome, such as `settled: deployed version 2` or `settled: failed at health_gate: health_gate_failed`;
- after `settled: deployed`, a `checked:` line saying the health check requested the health path alone, so request your other routes and read `read_logs` for errors;
- on a failure, the platform's reading of the likely cause and the [health check](/concepts/glossary#health-check-and-health-path)'s facts, never your application's own output;
- last, a line that gives the `read_status` call, which returns the whole record.

Before the upload, where the preparing call's response says the environment runs no version yet and names the manifest's health path, the command reads its zip for that path. Where no file names it, the command prints the platform's own refusal, uploads nothing, and ends with status 3.

A deploy usually ends within four minutes and has taken more than six, and the command stops waiting fifteen minutes after the deploy starts. Where your tool limits how long a shell command runs, allow this one fifteen minutes and the upload's time. Where your tool cannot allow that long, run the line as a background job and read its output when your tool reports that it ended. With `TURNZERO_DEPLOY_NO_WAIT` set to any value, the command returns once the deploy has started, and `read_status` shows the outcome.

The warning for a file that looks like a key or a credential refuses nothing, so under `deploy` the upload it reports is already under way. Where the file holds a real key, replace that key with a new one, because a deployed version keeps the files of its zip. Then move the file out of the folder and deploy again with a new `deploy` call and its line.

The figure after `at` on a step line counts seconds from the deploy's start. Each step line after the first also says how long the step before it took, as in `step: compute_apply at 40s, image_build took 40s`. A step your manifest needs nothing from is still listed and ends at once.

While it waits, the command reads the progress at most 450 times. Each read is bounded at 60 seconds, and the command pauses two seconds after a read that brings nothing new. Where the platform refuses the upload or the start, the command prints the refusal's name and explanation as the platform gave them.

The platform checks whether the upload's grant allows a start in the environment that `--env` names. Where the line names no `--env`, the start names the environment the preparing call returned. Where the platform refuses the start, the upload is already stored and the command ends with status 3. To go on, run the same line again.

A progress read that returns status 502, 503, or 504 has met a failure that is often temporary. The command prints a line that says so and makes the read again after 2, then 4, then 8 seconds, at most three more times for one read, each counted among the 450. A read that still fails ends the wait with status 2. The command makes the upload and the start once each, and never again, because either may already have taken effect.

`check` prints these lines, in this order:

- the `zip:` line, as `deploy` prints it, ending with the zip's hash;
- then the lines `deploy` prints after its `zip:` line, from `files:` to the `warning:` lines, less the health path warning on a first deploy, where a `refused:` line reads the recorded path;
- `refused:` with a refusal's name and the platform's explanation, one line per refusal of the application's state in the deploy's order, then one per refusal of the zip;
- `manifest:`, where the zip's layout passed its checks and its `manifest.json` names another health path than the recorded manifest, which a deploy reads; call `submit_manifest` with the zip's copy to deploy under it;
- last, `checked:` with the count of the refusals, or that no check would refuse a deploy now.

A refused call, or one with no usable response, prints the refusal or a sentence saying so and no later line.

The other subcommands print these lines:

- `secret` prints what [Supply a secret value without exposing it](/guides/supply-a-secret-value-without-exposing-it#what-the-command-reads-and-prints) describes, and `put` the `put:` line [Store files](/guides/store-files#an-upload-grant-from-your-tool) describes.
- `export download` prints the name of each file it writes under an escaped name or finds moved. It ends with one line that opens with `downloaded:` and counts the files on disk. That line also counts the files read in this run, already on disk, moved, failed, and not read.
- `library take` prints a `taken:` line; for an entry with compiled modules, a `copied:` line and an `installed:` line; then a `packages:` line and a `next:` line. The `packages:` line says whether the command wrote the rows into the application manifest. That file 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.
- `provision` prints the environment file's settings, each credential as a count of characters, then a line about the development database. `run` prints up to four lines of its own before the application's output: the folder, the settings the file sets, any setting where the file wins over your shell, and the port line. They print no value but `PORT`'s.
- `scaffold`, where the line names no `--template`, first prints a `template:` line saying it wrote `hello-world`. It then prints a `written:` line for each file it writes, and the `taken:` and `copied:` lines of `library take` under a template that takes a package. Then come npm's output, an `installed:` line, a `tested:` line, and the next steps, numbered, after a line that opens with `next:`.
- `authorize`, `logout`, and `token` print what [This computer's token](/concepts/how-the-turnzero-command-finds-its-credential#this-computer-s-token) describes.

`run` prints a port line that names where `PORT` comes from: `--port`, the environment file, or your shell. Where the value is a whole number from 1 to 65535, the line gives it and the address `http://localhost:<port>/`. Otherwise it names the source alone. Where nothing sets `PORT`, it says the application chooses its own port, which its own lines may name.

The application's output passes through. The command replaces a credential the application prints with its setting's name between angle brackets. It replaces the value of `TURNZERO_CLOUD_TOKEN` and of `APP_DATABASE_URL`. For every setting whose value is a connection string that contains a password, it replaces the whole value and the password, as the value spells it and with its percent escapes decoded. It finds no value printed in any other form, and replaces no value shorter than eight characters, so keep a value out of your application's output.

A shell reads a line's status right after it: `$?` in bash and zsh, `$LASTEXITCODE` in PowerShell after `npx.cmd`, and `%ERRORLEVEL%` in cmd. A PowerShell process started with `-Command` ends with 1 for any status but 0, so read `$LASTEXITCODE` inside it.

`run` is the one exception. It ends with the application's own status, whatever that is, so a status under `run` may be the application's and not the command's. Where a signal ended the application, the status is 128 plus the signal's number. After an interrupt on Windows, the status is npm's, or cmd's where the command started npm through cmd, and may not be the application's. Where no application was started, `run` ends with status 3 and the command's own lines say so.

While the application runs, an interrupt does not end the command before the application ends. A terminal passes an interrupt to the application itself. On macOS and Linux a termination or a hang-up is passed on to the application as it is. A first interrupt is passed on only where the command's standard input is not a terminal, and a second one as a termination.

On Windows the command passes nothing on: the application runs on the command's console, which hands it each interrupt itself. After an interrupt there, cmd asks `Terminate batch job (Y/N)?` once where the line was started through `npx.cmd`, after the command has ended. Type `N` or `Y` and press Enter: either returns your prompt, and the command's last line, after an empty line, says so. After `N` the line ends with the command's status, and after `Y` with cmd's own. A shell whose `npx` is not a batch file asks nothing: Git Bash, or PowerShell where scripts may run.

On Windows, a tool that ends the command's process outright, with no console interrupt, leaves the application running, so it ends the process tree it started, as [Start the application](/guides/run-your-application-on-your-machine#3-start-the-application) shows.

A refusal prints a line of the form `<step> refused (HTTP <status>): <error>`, followed by the platform's explanation. The `<step>` is the name of the command's step that was refused, such as `prepare`, `upload`, or `start`. A failure of the platform reads `<step> failed` in its place. A refusal of the command's own names the option and never repeats the value it was given, so a value typed into the wrong place is not printed.

Under this computer's token, a refusal of the preparing call closes by saying the credential was this computer's token, and that `authorize` authorizes the computer again. Under the variable's token, it closes as [A minted token in the environment](/concepts/how-the-turnzero-command-finds-its-credential#a-minted-token-in-the-environment) says. Where the platform refuses the call `rate_capped`, the same line may run again after the wait the response names. The `check_deploy` call's refusals print under the step `check`, closed in the same way.

## Related

- [The turnzero command](/concepts/turnzero-command) gives the lines your tool runs, a deploy from call to outcome, and the four statuses.
- [How the turnzero command finds its credential](/concepts/how-the-turnzero-command-finds-its-credential) says which credential each line reads and where it sends it.
- [turnzero command reference](/reference/turnzero-command) gives each subcommand's usage line, its options, and the statuses it ends with, generated from the command's own sources.
- [What the deploy zip holds](/concepts/what-the-deploy-zip-holds) says what a deploy's zip leaves out and the limits it checks.
- [Run your application on your machine](/guides/run-your-application-on-your-machine) runs `provision` and `run`.
- [Deploys](/troubleshooting/deploys) starts from a line that was refused or ended early.