turnzero command reference #
Generated automatically from the turnzero command's own texts, the ones its --help prints.
The turnzero command says what the command is and how your AI tool runs it, and How the turnzero command finds its credential says which credential each line reads. This page gives each subcommand's usage line, its options, and the statuses it ends with.
In a usage line, <command> stands for the line's head, npx -y turnzero@<tag>. The tag is latest on https://turnzero.ai, and next on Turn Zero's development platform. A part in square brackets is optional.
Each status has one meaning under every subcommand, and each section says what it means there:
- 0: done.
- 1: the act ran and failed, in whole or in a part the printed lines name.
- 2: the outcome is unknown, or the run stopped before its end, and the printed sentence names the call that reads the outcome or the line to run next. The command also ends 2 where it stops on an error of its own, and its last line says so.
- 3: nothing was started.
hash #
<command> hash [--path <folder or .zip file>] [--list] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--path |
<folder or .zip file> |
The application folder to zip as deploy zips it, or a .zip file whose bytes to hash as they are. Where absent, the folder the command runs in. |
--list |
None: a flag | After the hash and any warnings, prints one line for each file the zip holds: its size in bytes, then its name. It shows what a deploy from the folder would upload. It lists a folder's zip only, so it is refused beside a --path that names a .zip file. |
--origin |
<origin> |
The platform's address, as a line copied beside a deploy line carries it. The hash subcommand sends no request, so the address names nothing for it: it is checked as under deploy, then set aside. |
Its statuses:
- 0: the hash printed.
- 3: no hash was printed.
deploy #
<command> deploy --application <application id> [--origin <origin>] [--path <folder or .zip file>] [--rotate-database-credential] [--env <environment>]
Its options:
| Option | Value | Description |
|---|---|---|
--application |
<application id> |
The application to deploy, by its id, a lowercase UUID, as the line a deploy call from your tool answers names it. Required. |
--origin |
<origin> |
The platform's address. Where absent, the address TURNZERO_CLOUD_ORIGIN holds, or https://turnzero\.ai where it is unset. Under TURNZERO_CLOUD_MINTED_TOKEN the token is sent only to https://turnzero\.ai or to the address TURNZERO_CLOUD_ORIGIN holds. Otherwise it names the address whose token the command reads from this computer's credential file, and that token is sent to that address alone. |
--path |
<folder or .zip file> |
The application folder to zip and upload, or a .zip file to upload as it is. Where absent, the folder the command runs in. |
--rotate-database-credential |
None: a flag | Rotates production's database credential with this deploy, as the line a deploy call naming rotate_database_credential answers carries it. |
--env |
<environment> |
The environment to deploy to, development or production. Where absent, the platform chooses, and the command deploys to the environment the platform answers. The line a deploy call answers names none. |
Its statuses:
- 0: the version deployed, or the deploy started where TURNZERO_DEPLOY_NO_WAIT is set.
- 1: the deploy failed.
- 2: the wait stopped, or the start drew no answer: the deploy may go on, and read_status reads it.
- 3: an option, the credential, or the folder was refused, no credential was read, the preparing call answered no usable upload, the zip holds no file at the health path, the upload or the start was refused, or the upload drew no answer.
check #
<command> check --application <application id> [--origin <origin>] [--path <folder or .zip file>]
Its options:
| Option | Value | Description |
|---|---|---|
--application |
<application id> |
The application whose deploy to check, by its id, a lowercase UUID, as the line a check_deploy call from your tool answers names it. Required. |
--origin |
<origin> |
The platform's address. Where absent, the address TURNZERO_CLOUD_ORIGIN holds, or https://turnzero\.ai where it is unset. Under TURNZERO_CLOUD_MINTED_TOKEN the token is sent only to https://turnzero\.ai or to the address TURNZERO_CLOUD_ORIGIN holds. Otherwise it names the address whose token the command reads from this computer's credential file, and that token is sent to that address alone. |
--path |
<folder or .zip file> |
The application folder to zip as deploy zips it, or a .zip file to check as it is. Where absent, the folder the command runs in. Nothing is uploaded. |
Its statuses:
- 0: none of the checks would refuse a deploy now.
- 1: a deploy would be refused now, the refused: lines naming each refusal.
- 3: nothing was checked: an option, the credential, or the folder was refused, no credential was read and the two routes to one were printed, or the check call was refused, drew no answer, was redirected, or was answered by a failure.
secret #
[echo <secret grant> |] <command> secret store|rotate --name <name> [--application <application id>] [--environment <environment>] [--value-file <file>] [--value-variable <variable name>] [--value-prompt] [--restart] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--name |
<name> |
The name the value is stored under, as the line the store_secret or rotate_secret call answers names it. Required. |
--application |
<application id> |
The application whose scope holds the secret. Where absent, the account's scope. |
--environment |
<environment> |
The environment of that application whose scope holds the secret, development or production. It goes with --application. |
--value-file |
<file> |
The file that holds the value, read as UTF-8 with one trailing line end dropped. Give exactly one of this, --value-variable, and --value-prompt. |
--value-variable |
<variable name> |
The name of an environment variable that holds the value, for a run where a machine sets it, such as a hosted run's secrets store. The line names the variable, never its value, and an unset or empty variable is refused. |
--value-prompt |
None: a flag | Asks for the value at the terminal without showing it. It needs a terminal of your own, one that also shows the command's output: in a tool's shell the command refuses it, and the line takes --value-file instead. |
--restart |
None: a flag | Under rotate alone, with no grant piped: the write under this computer's token also restarts the environment whose running copy holds the old value, and the answer's restart says how. A line under a grant refuses it. |
--origin |
<origin> |
The platform's address. Where absent, https://turnzero\.ai; with no grant piped, the address TURNZERO_CLOUD_ORIGIN holds where it is set. With no grant piped, it names the address whose token the command reads from this computer's credential file, and that token is sent to that address alone. |
Its statuses:
- 0: the value written.
- 2: the write drew no answer, or an answer that is not a refusal: list_secrets shows when the name was last written.
- 3: nothing was written.
put #
echo <upload grant> | <command> put --area <area> --name <name> --path <file> [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--area |
<area> |
The storage area the file lands in, one of the application's, as the line the mint_upload_grant call answers names it. Required. |
--name |
<name> |
The name the file is stored under in the area, as the line names it. Required. |
--path |
<file> |
The file on this machine to upload, sent as it is. Required. |
--origin |
<origin> |
The platform's address. Where absent, https://turnzero\.ai\. |
Its statuses:
- 0: the file written.
- 2: the write drew no answer, or an answer that is not a refusal: the file may have landed, and a fresh line writes it again.
- 3: nothing was written.
export download #
echo <download grant> | <command> export download --export <application id>/<export id> [--path <folder>] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--export |
<application id>/<export id> |
The application and its completed export, as the mint_download_grant call answered them, joined by a slash. Required. |
--path |
<folder> |
The folder the files are written into: a new or empty one, or one an earlier run of the same export wrote. Where absent, a new folder named for the export in the folder the command runs in, which is refused where that folder holds package.json, since a deploy from it would carry the export. |
--origin |
<origin> |
The platform's address. Where absent, https://turnzero\.ai\. |
Its statuses:
- 0: every file the manifest names on disk, moved ones reported.
- 1: a file failed, cut short or refused: the closing lines name the line run again, or a fresh export where a file was answered as an absent name.
- 2: the run stopped before the end: a fresh line from mint_download_grant resumes it.
- 3: an option, the grant, the folder, or the manifest was refused, and nothing was written.
library take #
<command> library take --entry <name> [--path <project root>] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--entry |
<name> |
The library entry to take, by the name list_library answers, such as storage or ui/styles. Required. |
--path |
<project root> |
The project's root: the folder that holds system/ or system.json beside app/, or, on a first take, the folder a new system/ is made in. Where absent, the folder the command runs in. |
--origin |
<origin> |
The platform's address. Where absent, https://turnzero\.ai\. |
Its statuses:
- 0: the entry taken, and installed where it carries compiled modules.
- 1: the entry, its row, and the copy written, and npm install failed or the application manifest's packages was not written.
- 3: nothing was written.
provision #
echo <secret grant> | <command> provision --application <application id> [--env-file <file>] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--application |
<application id> |
The application whose development settings are written, by the id create_application answered, as the line the submit_manifest call answers names it. Required. |
--env-file |
<file> |
The environment file to write. Where absent, .env in the folder the command runs in. An existing file keeps every line the command does not set. |
--origin |
<origin> |
The platform's address, which is also written as TURNZERO_CLOUD_API and TURNZERO_CLOUD_GATEWAY_URL. Where absent, https://turnzero\.ai\. |
Its statuses:
- 0: the settings written.
- 1: the settings written without a connection limit, which the platform's answer did not carry.
- 2: a credential was re-minted, or may have been, and its value was not written: the printed sentence names the run that re-mints again.
- 3: nothing was re-minted.
run #
<command> run [--path <folder>] [--env-file <file>] [--port <port>] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--path |
<folder> |
The application folder npm start runs in. Where absent, the folder the command runs in. |
--env-file |
<file> |
The environment file whose settings the application receives, as provision writes it. Where absent, .env in the folder the command runs in. A file that is not there is read as no settings. |
--port |
<port> |
The port the application listens on, a whole number from 1 to 65535, set as PORT over the file's line and the shell's. |
--origin |
<origin> |
The platform's address, as the other subcommands' lines carry it. run reads no origin, since it starts the application on this machine and sends no request: the option is taken so every line can carry it, checked as under deploy, then set aside. |
Its statuses:
- 0: the application ended with status 0.
- 3: no application was started.
scaffold #
<command> scaffold [--template <template>] [--resource <plural>] [--singular <singular>] [--fields <list>] [--path <project root>] [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--template |
<template> |
The template to write, one of hello-world, database-service, and scheduled-job, hello-world where absent. The hello-world template is the smallest service that deploys, whose one API route, GET /api/hello, answers hello world. The database-service template is a notes service that keeps its data in the platform's database. The scheduled-job template is the hello-world service with one handler, which the platform runs each hour through the Schedule package. |
--resource |
<plural> |
Under the database-service template, the resource the service keeps, by its plural, the word of its table and its route: an ASCII lower-case letter, then ASCII lower-case letters and digits, at most 30 characters, and never health. The files are written under its names where the template names notes, note, Notes, and Note, two file names among them. Where absent, the service keeps notes. A template that keeps no resource refuses it. |
--singular |
<singular> |
The resource's singular, in the same form, with --resource. Where absent, the plural without its closing s, so a plural that does not end in s needs it. |
--fields |
<list> |
Under the database-service template, the resource's columns: fields separated by commas, each a name, a colon, and a kind, such as "name:text,message:text", written between double quotes. A name is an ASCII lower-case letter, then ASCII lower-case letters, digits, and underscores, at most 30 characters, and never id. A kind is text, integer, boolean, or timestamp. Every column is required, and a list holds one to 20 fields. Where absent, the service keeps one text column, title. A template that keeps no resource refuses it. |
--path |
<project root> |
The project's root, the folder app/ and system/ are written in, made where it does not stand. Where absent, the folder the command runs in. |
--origin |
<origin> |
The platform's address. Where absent, https://turnzero\.ai\. |
Its statuses:
- 0: the files written and installed, the entry taken where the template takes one, and the tests passed.
- 1: the files written, and npm install or the tests failed.
- 2: the run stopped before its end, by an interrupt or another signal that ended npm, by an error of the command's own, or by something that came to stand at app while it wrote: the printed sentence names the way on.
- 3: nothing was written.
authorize #
[echo <token code> |] <command> authorize [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--origin |
<origin> |
The platform's address this computer is authorized at. Where absent, the address TURNZERO_CLOUD_ORIGIN holds, or https://turnzero\.ai where it is unset. A --origin the line names must be https://turnzero\.ai, https://dev\.turnzero\.ai, or the address TURNZERO_CLOUD_ORIGIN holds, an address of this machine only where TURNZERO_CLOUD_ORIGIN names it. |
Its statuses:
- 0: the challenge printed, or this computer authorized.
- 1: a token was minted and not kept, or the token this computer held before was not revoked: the printed lines name revoke_token.
- 2: the exchange drew no answer, or an answer that is not a refusal: list_tokens shows whether a token was minted.
- 3: nothing was minted: an option, the credential file, or the token code was refused, no request was pending, or the exchange was refused.
logout #
<command> logout [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--origin |
<origin> |
The platform's address whose authorization this computer ends. Where absent, the address TURNZERO_CLOUD_ORIGIN holds, or https://turnzero\.ai where it is unset. |
Its statuses:
- 0: the entries removed and the token revoked or ended, or none was kept.
- 1: the token was refused its revocation, or the credential file could not be written after it: the printed lines name revoke_token.
- 2: the revocation drew no answer, or an answer that is not a refusal: list_tokens shows whether the token stands.
- 3: nothing was sent or removed: an option or the credential file was refused.
token #
[echo <token code> |] <command> token request|claim [--origin <origin>]
Its options:
| Option | Value | Description |
|---|---|---|
--origin |
<origin> |
The platform's address the token is minted at. Where absent, the address TURNZERO_CLOUD_ORIGIN holds, or https://turnzero\.ai where it is unset. A --origin the line names must be https://turnzero\.ai, https://dev\.turnzero\.ai, or the address TURNZERO_CLOUD_ORIGIN holds, an address of this machine only where TURNZERO_CLOUD_ORIGIN names it. |
Its statuses:
- 0: the challenge printed, or the value printed once.
- 1: the token minted was an authorized computer's, and is revoked where it could be: the printed lines name revoke_token.
- 2: the exchange drew no answer, or an answer that is not a refusal: list_tokens shows whether a token was minted.
- 3: nothing was minted: an option, the credential file, the token code, or a standard error that is no terminal was refused, no request was pending, or the exchange was refused.