# CLI reference

`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

```sh
zya new [directory]
```

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

```sh
# 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

```sh
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 |

```sh
# 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

```sh
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 |

```sh
# 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

```sh
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 |

```sh
# 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

```sh
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 |

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

### zya builds view

Show a build's result and the steps it ran

```sh
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 |

```sh
# 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

```sh
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 |

```sh
# 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

```sh
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 |

```sh
# 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

```sh
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 |

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

### zya secrets delete

Delete a project secret

```sh
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 |

```sh
# Remove a secret
zya secrets delete API_TOKEN
```

## Account

### zya login

Sign in with your Zenitya account, or save a machine key for CI

```sh
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) |

```sh
# 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

```sh
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

```sh
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 |

```sh
# For scripts
zya whoami --json
```

## Help

### zya docs

Read the documentation for this version of the CLI

```sh
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 |

```sh
# 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

```sh
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 |

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

# Install it
zya update
```