The turnzero-cloud command's options and output

The turnzero-cloud command's options and output are the reference half of The turnzero-cloud command: what each line reads beside its credential, what it prints, how each subcommand ends, and the options each one takes. 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-cloud command finds its credential says which credential each line reads.

What it reads

The credential each line reads is How the turnzero-cloud 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 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-cloud/<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 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:

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 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 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'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.

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 What the command reads and prints describes, and put the put: line Store files 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 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 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 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.

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.

How each subcommand ends

How it ends gives the four statuses and the next step after deploy and check. This table gives what each status means under every subcommand.

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.

authorize, logout, and token end as How authorize, logout, and token end says.

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 shows.

Options

A subcommand is one word. A subcommand 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. 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.

Where each line's credential comes from gives the credential each subcommand reads.

The deploy subcommand takes these options, each as the line gives it:

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.

The hash subcommand takes three options. It sends no request, so --origin names no address for it, and any other option ends it with status 3:

Where your application's folder or zip is somewhere else, name it with --path. 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.

The check subcommand takes three of the options deploy takes, each read as deploy reads it. It takes no --env, since it checks the environment the platform would deploy to:

The secret subcommand takes these options, each as the line gives it:

The put subcommand takes these options, each as the line gives it:

The export download subcommand takes these options, each as the line gives it:

The library take subcommand takes these options:

The provision subcommand takes these options:

The run subcommand takes these options:

The scaffold subcommand takes these options:

The command ends with status 3 before it sends any request or writes anything where a --resource or --singular is outside that form, or the plural is s alone. It ends the same way where the plural has no closing s and no --singular, where --singular comes without --resource, and where it cannot read a --fields list. The printed sentence names the option and what it takes.

The authorize subcommand takes this option:

The logout subcommand takes this option:

The token subcommand takes this option, under token request and token claim alike:

--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.

Related

• The turnzero-cloud command gives the lines your tool runs, a deploy from call to outcome, and the four statuses.
• How the turnzero-cloud command finds its credential says which credential each line reads and where it sends it.
• What the deploy zip holds says what a deploy's zip leaves out and the limits it checks.
• Run your application on your machine runs provision and run.
• Deploys starts from a line that was refused or ended early.