---
title: "CLI guide"
description: "Keep .env files in Secrets with ezgh secrets: create, update, read, binary values, versions and deleting."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI guide

`ezgh secrets` works in a project: pass `--project`, or set `EZGH_PROJECT` or the profile's
project. Name a secret by its name (`prod/app`) or its ID. Only `ezgh secrets read` prints values,
and it's a billed read. Every other command shows names and metadata. See the
[reference](/cli/reference/secrets) for every flag.

## Create a secret from a `.env` file

```sh
ezgh secrets create prod/app --from-env-file .env --description "Production app"
```

The file is `KEY=VALUE` lines. Blank lines and `#` comments are skipped, `export` prefixes are
accepted, and values can be unquoted, `'single quoted'` (literal) or `"double quoted"` (with `\n`,
`\r`, `\t`, `\"`, `\\` and `\$` escapes, and across lines). A key that appears twice takes its last
value. That creates version 1.

Add fields with `--set KEY=VALUE`, which wins over the file. Without `--from-env-file` or `--set`
the secret starts empty and has no `latest` until you write a version.

## Change values: `put`

`put` writes a new version. By default it builds on `latest`, so every field you don't mention is
carried over:

```sh
ezgh secrets put prod/app --set API_KEY=new --remove OLD_KEY
ezgh secrets put prod/app --from-env-file .env.rotation
```

- `--base N` builds on version `N` instead of `latest`.
- `--replace` makes the new version exactly the fields you give, dropping every other field. It
  needs `--from-env-file` or `--set`, and doesn't take `--base` or `--remove`.
  `ezgh secrets put prod/app --from-env-file .env --replace` makes the secret match the file.
- If the secret changed since the base was read, the write fails with a conflict. Run it again.
- `--set KEY=-` reads a value from standard input (once per command).

## Read values: `read`

```sh
ezgh secrets read prod/app > .env
eval "$(ezgh secrets read prod/app)"
ezgh secrets read prod/app --version 2 --format json
ezgh secrets read prod/app --field DB_PASSWORD --format raw
```

| `--format` | Output |
| --- | --- |
| `env` (default) | `KEY=VALUE` lines in name order, quoted for a POSIX shell when a value needs it, so `eval` and `set -a; . <(...)` work |
| `json` | The API's answer: `{ "version", "fields" }`, or `{ "version", "name", "value" }` with `--field`. A binary value is `{ "base64": "..." }`. |
| `raw` | One value's exact bytes, with no newline added. Needs `--field`. |

`--version` is a number or `latest` (the default), and `--field` reads one field. Reading
another version or one field is still a billed read.

> **Caution**
>
> The `env` format can't carry binary values, and `ezgh` refuses a secret that has one: read the
> field with `--field NAME --format raw`, or use `--format json`. Field names can contain `.` and
> `-`, which Secrets allows but shells don't accept in variable names. `ezgh` prints such a field in
> `env` format, and a shell that evaluates it can't use it. Use `--format json` for those secrets,
> or choose names of letters, digits and `_`.

## Binary values

`--set KEY=@file` reads the value from a file, and `ezgh` sends a file that isn't valid UTF-8 as
binary. Binary values are up to 8 KiB like any other:

```sh
ezgh secrets create prod/tls --set TLS_CERT=@cert.der --set TLS_KEY=@key.der
ezgh secrets read prod/tls --field TLS_KEY --format raw > key.der
```

## Versions

```sh
ezgh secrets versions prod/app
ezgh secrets destroy-version prod/app 2
```

`versions` lists versions, newest first, with their state, field count and who wrote them; field
names are in `-o json`. `destroy-version` erases a version's values for good, after asking to
confirm (`--yes` skips the question). See [Concepts](/secrets/concepts#versions).

## List, inspect and delete

```sh
ezgh secrets list
ezgh secrets get prod/app
ezgh secrets delete prod/app
```

`get` shows the secret's counts and the field names of `latest`, never values. `delete` erases the
secret and every version, after asking to confirm (`--yes` skips the question). See
[Deleting secrets](/secrets/concepts#deleting-secrets-and-versions).

`ezgh secrets grants list` and `ezgh secrets grants revoke` manage [grants](/secrets/grants).

Source: https://docs.ezghcloud.com/secrets/cli/index.mdx