Secrets · Reference
CLI
mybeast-secrets reads one environment with a service token, and writes it to a .env or starts a command with it. One bash file: bash 3.2 or newer and curl, nothing else.
Install
Download the file from the latest release of my-beast/cli into a folder on your PATH, and make it executable:
curl -fsSLo ~/.local/bin/mybeast-secrets https://github.com/my-beast/cli/releases/latest/download/mybeast-secrets
chmod +x ~/.local/bin/mybeast-secrets
mybeast-secrets --version~/.local/bin must exist and be on your PATH; any other folder on it will do.
Check the download
Each release lists its files' SHA-256 sums in SHA256SUMS. To check the file against it:
cd ~/.local/bin && curl -fsSL https://github.com/my-beast/cli/releases/latest/download/SHA256SUMS | grep ' mybeast-secrets$' | shasum -a 256 -c -It prints mybeast-secrets: OK when the file is the released one. On Linux without shasum, end the line with sha256sum -c - instead.
In CI and on servers, pin a release rather than latest, so every machine runs the same file:
https://github.com/my-beast/cli/releases/download/v0.1.0/mybeast-secretsSettings
Two variables in the environment it runs in, as the Tokens page shows them when a token is made:
export MYBEAST_SECRETS_URL=https://services.my-beast.com/secrets
export MYBEAST_SECRETS_TOKEN=st_….…| Variable | What it is |
|---|---|
MYBEAST_SECRETS_URL | Secrets' address, https://services.my-beast.com/secrets. It must be https://; plain http:// is taken only for localhost, 127.0.0.1, *.localhost and *.test. |
MYBEAST_SECRETS_TOKEN | A service token, st_….…. It decides which project and environment are read: see Manage service tokens. |
The token goes to curl on its standard input, never on a command line, where other users' ps would see it. A read gives up after 30 seconds.
pull
mybeast-secrets pull [--out FILE] [--force]Writes the environment to a .env.
| Flag | What it does |
|---|---|
--out FILE | Where to write. .env in the current folder by default; --out=FILE works too. With --out - it prints the file to standard output and writes nothing. |
--force | Overwrite the file even if mybeast-secrets didn't write it. |
-h, --help | Print the usage. |
- The file is written next to its place, readable by its owner only (mode
600), and moved into place whole. A reader never sees half a file, and a failed read writes nothing. - It overwrites only a file whose first line is the one Secrets writes,
# MyBeast Secrets · …: a file it pulled before, or one downloaded from the .env page. Any other file is left alone unless you add--force. - When it's done, it says so on standard error, with the file's first line:
mybeast-secrets: wrote .env (MyBeast Secrets · shop/production · change #12 · 4 variables · 27.10.2026 14:05 UTC)run
mybeast-secrets run -- COMMAND [ARGS...]Reads the environment, puts every variable into the environment of COMMAND and starts it in its place (exec). Nothing is written to disk. The -- keeps the command's own flags apart.
- A variable that's already set in the shell is replaced by the environment's value; the rest of the shell's environment is passed on as it is.
- The answer is read as
export NAME=$'…'lines and decoded, never run as shell code. A line of any other shape stops it before the command starts. - If the read fails, the command isn't started.
Values reach the command exactly
$, backticks, line breaks and Unicode arrive in the command's environment as they are in Secrets.Help and version
mybeast-secrets --help(or-h,help, or no command at all) prints the usage.mybeast-secrets --version(or-v) prints its name and version.
Exit codes and messages
| Status | When |
|---|---|
| 0 | pull wrote or printed the file; --help or --version. |
| 1 | It stopped, with one line on standard error saying why. Nothing was written and nothing was run. |
| The command's | After run starts the command, the status is the command's own. |
Every message starts with mybeast-secrets:. The ones you may meet, and what to do:
| Message | Why, and the fix |
|---|---|
| MYBEAST_SECRETS_URL is not set (e.g. https://services.my-beast.com/secrets) | The machine's environment lacks the address. Set it as the Tokens page shows. |
| MYBEAST_SECRETS_TOKEN is not set (a service token: the project's Secrets → Tokens) | The machine's environment lacks the token. Make one on the Tokens page and set it. |
| MYBEAST_SECRETS_URL must be https:// (plain http only for localhost, *.localhost and *.test) | The address starts with http:// on a public host. Use https://services.my-beast.com/secrets. |
| MYBEAST_SECRETS_TOKEN does not look like a service token (st_….…) | The value isn't a whole token: st_, letters and digits, a dot, then the secret. Copy both lines again from where you kept them, or make a new token. |
| curl is needed | The machine has no curl on its PATH. Install it with the system's package manager. |
| could not reach https://services.my-beast.com/secrets | No answer within 30 seconds, or no connection at all: DNS, a firewall, a proxy. curl's own reason is printed on the line before. |
| the token was refused: revoked, mistyped, or not a token of https://services.my-beast.com/secrets | The API answered 401. See The token is refused. |
| too many reads just now; try again in a minute | The API answered 429: more than 120 reads a minute with this token. See Too many reads. |
| https://services.my-beast.com/secrets answered 503 | Any other status. Nothing was written and nothing was run: try again in a few minutes. |
| .env was not written by mybeast-secrets; move it away, or pull with --force to overwrite it | A .env is already there, and its first line isn't the marker a pull writes. See A pull won't overwrite the .env. |
| cannot write in config | pull can't make a file in the folder of --out: it doesn't exist, or the user can't write there. |
| the answer has a line that is not a variable; nothing was run | run got something other than variables, such as a proxy's page. The command was not started. |
| run needs a command: mybeast-secrets run -- COMMAND [ARGS...] | run was given no command to start. |
| pull does not take --env (see mybeast-secrets --help) | A flag pull doesn't know. The token decides the environment: there is no flag for it. |
| unknown command push (see mybeast-secrets --help) | The commands are pull and run. |