CLI reference

Every zya command, option and example.

zya and zenitya are the same program. Every command prints its own help with --help; this page collects them.

Global options

Option	Description
`-h, --help`	Show help for a command
`-v, --verbose`	Show error details and stack traces
`--version`	Print the CLI version

Environment

Variable	Description
`ZENITYA_API_KEY`	Machine key; takes precedence over a saved login
`ZENITYA_API_URL`	API origin (default: https://api.zenitya.com)
`ZENITYA_CONFIG_FILE`	Path to zenitya.json
`ZENITYA_HOME`	Credentials and the installed CLI (default: ~/.zenitya)
`NO_COLOR`	Disable color

Project

zya new

Create a project with an example tool

shell

zya new [directory]

Argument	Description
`<directory>`	Where to create it (default: the current directory)

shell

# Create a project in ./my-tools
zya new my-tools

zya deploy

Upload the project's source and wait for the remote build to go live

shell

zya deploy [options]

Option	Description
`--json`	Print the build result as JSON on stdout
`--idempotency-key <key>`	Reuse the key a lost deploy printed, to resume it instead of building again
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Deploy the project in this directory
zya deploy

# Get the build ID in a script
zya deploy --json | jq -r .buildId

Source is uploaded and built remotely; nothing is built on this machine. Hidden files such as .env are never uploaded; set project secrets instead.

zya exec

Run a tool on the active deployment, or from local source with --local

shell

zya exec <tool> [options]

Argument	Description
`<tool>`	The tool's key, as `zya tools list` shows it

Option	Description
`-d, --data <json>`	JSON input for the tool (default: read from stdin)
`-l, --local`	Run the source on this machine instead of the active deployment
`--dotenv <path>`	With --local: load this env file instead of .env
`--no-dotenv`	With --local: do not load .env
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Call echo on the active deployment
zya exec echo --data '{"message":"hi"}'

# Run echo from source on this machine
zya exec echo --local --data '{"message":"hi"}'

# Read the input from a file
zya exec echo < input.json

The tool's output is printed on stdout and its logs on stderr. Remote runs never read .env files and never fall back to running locally.

zya tools list

List the project's deployed tools that your credential can call

shell

zya tools list [options]

Option	Description
`--json`	Print JSON on stdout instead of a table
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Show the tools you can call in this project
zya tools list

# Only their keys
zya tools list --json | jq -r '.tools[].key'

zya builds list

List the project's builds, newest first

shell

zya builds list [options]

Option	Description
`--limit <count>`	How many builds to show, 1–100 (default: 10)
`--json`	Print JSON on stdout instead of a table
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# The five most recent builds
zya builds list --limit 5

zya builds view

Show a build's result and the steps it ran

shell

zya builds view <build-id> [options]

Argument	Description
`<build-id>`	Build ID, as printed by `deploy` and `builds list`

Option	Description
`--json`	Print JSON on stdout instead of a table
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Steps, timings and the deployment a build produced
zya builds view <build-id>

zya builds logs

Print a build's output from dependency install, bundling and tool discovery

shell

zya builds logs <build-id> [options]

Argument	Description
`<build-id>`	Build ID, as printed by `deploy` and `builds list`

Option	Description
`--phase <step>`	Only one step's output: install, bundle, describe
`-f, --follow`	Keep printing new output until the build finishes
`--json`	Print one JSON record per line on stdout
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Everything the build printed
zya builds logs <build-id>

# Only dependency installation
zya builds logs <build-id> --phase install

# Keep printing while the build runs
zya builds logs <build-id> --follow

Configuration

zya secrets set

Create or replace a project secret

shell

zya secrets set <name> <value> [options]
zya secrets set <name> --stdin [options]

Argument	Description
`<name>`	Secret name, e.g. API_TOKEN
`<value>`	Secret text, kept exactly as given; omit it and use --stdin to keep it out of shell history

Option	Description
`--stdin`	Read the value from piped stdin
`--json`	Print metadata as JSON on stdout (never values)
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Set a value
zya secrets set API_TOKEN "example-token"

# Read it from a file, out of shell history
zya secrets set PRIVATE_KEY --stdin < key.pem

Values are kept exactly as given, 1–16 KiB of UTF-8. Deployed tools read them as environment variables; exec --local does not.

zya secrets list

List the project's secret names and when each changed

shell

zya secrets list [options]

Option	Description
`--json`	Print metadata as JSON on stdout (never values)
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Names and when each changed; values are never shown
zya secrets list

zya secrets delete

Delete a project secret

shell

zya secrets delete <name> [options]

Argument	Description
`<name>`	Secret name, e.g. API_TOKEN

Option	Description
`--json`	Print metadata as JSON on stdout (never values)
`--config-file <path>`	Use this zenitya.json (default: the nearest one from the current directory up)
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# Remove a secret
zya secrets delete API_TOKEN

Account

shell

zya login [options]

Option	Description
`--no-browser`	Print the sign-in link instead of opening a browser
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Save this machine key instead of signing in (or set ZENITYA_API_KEY)

shell

# Sign in in the browser and choose an organization
zya login

# Print the sign-in link to open yourself
zya login --no-browser

For CI, set ZENITYA_API_KEY to a machine key instead; it takes precedence over a saved login.

zya logout

Sign out: revoke this login's access and remove the saved credential

shell

zya logout [options]

Option	Description
`--local`	Only remove the saved credential, without contacting the API (when offline)

zya whoami

Show the account and organization commands run as

shell

zya whoami [options]

Option	Description
`--json`	Print JSON on stdout instead of a table
`--api-url <url>`	Zenitya API origin (default: the saved login's, else https://api.zenitya.com)
`--token <key>`	Machine key; prefer ZENITYA_API_KEY to keep it out of shell history

shell

# For scripts
zya whoami --json

Help

zya docs

Read the documentation for this version of the CLI

shell

zya docs [topic] [options]

Argument	Description
`<topic>`	The page to print as markdown (default: list the pages)

Option	Description
`--json`	List the pages as JSON on stdout

shell

# List the pages
zya docs

# How an agent should use this CLI
zya docs agents

# From install to a deployed tool
zya docs quickstart

CLI

zya update

Update the CLI to the newest release

shell

zya update [options]

Option	Description
`--check`	Only report whether an update is available
`--tag <tag>`	Install this cli-v<version> release instead of the newest

shell

# See whether a newer CLI is available
zya update --check

# Install it
zya update

CLI reference

##Global options

##Environment

##Project

zya new

zya deploy

zya exec

zya tools list

zya builds list

zya builds view

zya builds logs

##Configuration

zya secrets set

zya secrets list

zya secrets delete

##Account

zya login

zya logout

zya whoami

##Help

zya docs

##CLI

zya update

Global options

Environment

Project

Configuration

Account

Help

CLI