reoclo secrets

reoclo secrets projects ls
reoclo secrets projects create    [options] <name>
reoclo secrets projects update    [options] <project>
reoclo secrets projects duplicate [options] <project>
reoclo secrets ls     [options]
reoclo secrets get    [options] <key>
reoclo secrets set    [options] <key>
reoclo secrets rm     [options] <key>
reoclo secrets import [options]
reoclo secrets inject [options]

Every subcommand except projects ls and inject operates on a single secret project. Pass --project <name> to select it, by name or by id. projects create takes the new project’s name, and projects update and projects duplicate take the project as their argument instead.

Most subcommands require a signed-in session. Run reoclo login first. A machine user token (rk_m_, REOCLO_MACHINE_TOKEN) also works on these subcommands. What it can read depends on the secret projects granted to that machine user. What it can change depends on its role. get cannot read a secret project that is restricted to specific servers, the same as reoclo run. Use an automation key for that project. ls, set, and rm depend on the machine user’s project grant and role.

Automation keys (rca_) are rejected with exit code 4: they are for reoclo run, which injects values without ever exposing them. If you export REOCLO_AUTOMATION_KEY in your shell it takes precedence over your stored session, and those subcommands will refuse to run. An exported REOCLO_MACHINE_TOKEN ranks higher still: it silently runs every secrets subcommand as that machine user instead of your signed-in session.

inject is the exception. It accepts a login session, an automation key, or a machine user token (CLI 0.68.0 or newer). It can render a template in CI next to reoclo run.

projects ls

Lists the secret projects you can see.

$ reoclo secrets projects ls
ID                                    NAME                 DESCRIPTION
019ee15f-0907-7442-8377-4afdc2791059  payments-production  Stripe and Postgres for prod
019f1fa9-73d7-7281-bb85-fb61e87ac8a6  payments-staging

projects create <name>

Creates an empty secret project. The name is trimmed and must not be empty. Needs the permission to write secret projects.

Flag	Meaning
--description <text>	The project description

reoclo secrets projects create payments-staging --description "Stripe and Postgres for staging"

The command prints the created project (use -o json to script against its id). It refuses a name that another project already uses (exit code 2), because --project <name> must match exactly one project. To bind the new project to an application when you create it, pass --bind to reoclo apps create.

projects update <project>

Renames a project or changes its description. Pass the project by name or by id. Pass at least one flag. Requires the developer role. Available in CLI 0.82.0 and newer.

Flag	Meaning
--name <name>	The new name (1 to 120 characters)
--description <text>	The new description (up to 500 characters). An empty string removes it
--clear-description	Removes the description

reoclo secrets projects update payments-production --description "Stripe and Postgres for prod"
reoclo secrets projects update payments-production --name payments-prod
reoclo secrets projects update payments-prod --clear-description

Keys, values, access grants, and app bindings do not change. A rename does change what --project <name> matches: update scripts and CI workflows that select the project by name, or select it by id, which is stable. The command refuses a name that another project already uses (exit code 2), because --project <name> must match exactly one project. Descriptions and names are trimmed; a description that is only whitespace is removed.

projects duplicate <project>

Copies a project into a new project in the same organization. Every key keeps its current value. The copy happens on the server: values stay encrypted and are never sent to the CLI. Requires the developer role. Available in CLI 0.84.0 and newer.

Flag	Meaning
--name <name>	The name for the copy (1 to 120 characters). Default: the source name plus (copy)
--copy-grants	Also copy the manual access grants. Requires the admin role

reoclo secrets projects duplicate payments-production --name payments-staging
reoclo secrets projects duplicate payments-production --copy-grants

The copy starts fresh in three ways. Each secret starts at version 1 with no history. A synced 1Password or Bitwarden secret becomes a manual secret in the copy, so the two projects do not share a sync source. The API does not copy app bindings, because a binding belongs to the app.

Without --copy-grants the copy has no access grants. With --copy-grants, the API copies only the grants that an admin added by hand. It never copies the grants that mirror app env references, because it maintains those automatically. The command refuses a --name that another project already uses (exit code 2).

ls

Lists the keys in a project with their current version number. Values are never returned.

$ reoclo secrets ls --project payments-production
KEY               VERSION
DATABASE_URL      3
STRIPE_API_KEY    1
WEBHOOK_SECRET    2

get <key>

Reveals a single value and writes it to stdout with no trailing formatting, so it composes with other tools.

reoclo secrets get DATABASE_URL --project payments-production

Every reveal is written to the audit log before the value is returned. Avoid echo-ing the result in CI: assign it, or prefer reoclo run, which never exposes the value at all.

set <key>

Creates a secret, or adds a new version to an existing one. Previous versions are retained and can be rolled back to from the dashboard.

reoclo secrets set STRIPE_API_KEY --project payments-production --value 'sk_live_...'
reoclo secrets set TLS_CERT       --project payments-production --from-file cert.pem
echo -n 'hunter2' | reoclo secrets set DB_PASSWORD --project payments-production

Flag	Description
--project <name>	Target project, by name or id. Required.
--value <value>	The value, inline.
--from-file <path>	Read the value from a file.

Prefer --from-file or stdin over --value: an inline value appears in your shell history and in the process table. Both --from-file and stdin strip exactly one trailing newline, so a file written by an editor round-trips byte-for-byte.

rm <key>

Deletes a secret and all of its versions.

reoclo secrets rm OLD_TOKEN --project payments-production

Secrets that are kept in sync from 1Password or Bitwarden are read-only. Detach them in the dashboard first. See Importing and syncing secrets.

import

Bulk-imports secrets from another manager into a project. This runs on your machine and drives the provider’s own CLI, so that CLI must be installed and signed in. The value never passes through Reoclo’s servers on its way in.

reoclo secrets import --from onepassword --project payments-production --dry-run
reoclo secrets import --from onepassword --project payments-production --op-vault Engineering
reoclo secrets import --from bitwarden   --project payments-production --skip-existing

Flag	Description
--from <source>	onepassword or bitwarden. Required.
--project <name>	Target project, by name or id. Required.
--op-vault <id|name>	Limit a 1Password import to one vault.
--bws-project <id|name>	Limit a Bitwarden import to one Secrets Manager project.
--skip-existing	Skip keys that already exist instead of failing.
--dry-run	Print the plan and write nothing.

Requirements per source:

Source	Needs	Authenticated by
onepassword	the op CLI on your PATH	your existing op sign-in
bitwarden	the bws CLI on your PATH	BWS_ACCESS_TOKEN in your environment

Always dry-run first

Without --op-vault or --bws-project, an import reads every item the provider CLI can see, which for a personal 1Password sign-in can be hundreds of entries across every vault. --dry-run reports exactly how many keys would be written and skips the write entirely.

Keys are derived from the source entry as ITEMTITLE_FIELDLABEL, uppercased, with every run of non-alphanumeric characters collapsed to _. Colliding keys get a _2, _3 suffix. One-time-password fields, note fields, and empty values are skipped.

The import stops before writing anything if the source contains duplicate keys, or (unless you pass --skip-existing) if any key already exists in the target project. Values are written in batches. If a batch fails partway, the message tells you how many landed, and re-running with --skip-existing resumes.

For a browser-based import that takes a pasted token instead of a local CLI, see Importing and syncing secrets.

inject

Renders a template file of op:// references, and writes the result with each reference replaced by its resolved value. It is the drop-in for 1Password’s op inject, but the values come from Reoclo.

reoclo secrets inject -i app.env.tpl -o app.env
reoclo secrets inject -i app.env.tpl >> /opt/reoclo/.env

A template is a .env file whose values are op://<project>/<item>/<field> references. Reoclo maps each one to the secret <field> in the project <project>. It ignores the <item> segment.

# app.env.tpl
DATABASE_URL=op://payments-production/app/DATABASE_URL
STRIPE_API_KEY=op://payments-production/app/STRIPE_API_KEY

Flag	Description
-i, --input <path>	The template file to render. Required.
-o, --output <path>	Write the result to this file. The default is stdout.
-f, --force	Overwrite the output file if it already exists.

Only a whole value is a reference. An op:// in a comment, or in the middle of a value, stays as plain text. This is safer than op inject, which also reads references in comments.

Unlike the other secrets subcommands, inject accepts an automation key or a machine user token (CLI 0.68.0 or newer), as well as a login session. With either credential it resolves through a read-only session, so it runs in CI alongside reoclo run. Grant the credential read on each project the template names.

By default inject does not overwrite an existing output file. Pass -f to replace it.

Reoclo resolves the references, never 1Password, so the op command does not need to be installed. This is different from import, which reads your real 1Password or Bitwarden items.

The rendered file holds real secret values

inject writes resolved values to a file or to stdout. Write the output to a path only your deploy user can read, and delete it after the process that needs it has started. To keep the values out of every file, use reoclo run --env-file instead, which injects them straight into a process.

inject needs CLI 0.64.0 or newer

Earlier versions do not have this subcommand.

bind, bindings, and unbind

bind links a secret project to an application or a stack, so the project’s secrets inject as env vars at deploy time.

# every key in the project, into one application
$ reoclo secrets bind infra --app api

# selected keys only, into a stack (every member receives them)
$ reoclo secrets bind storage --group portfolio \
    --key MINIO_ROOT_USER --key MINIO_ROOT_PASSWORD

# rename on bind: one stored credential, two env names
$ reoclo secrets bind storage --app public-web \
    --key MINIO_ROOT_USER=S3_ACCESS_KEY_ID \
    --key MINIO_ROOT_PASSWORD=S3_SECRET_ACCESS_KEY

• --app <idOrSlug> or --group <idOrSlug>: exactly one target.
• --prefix <PREFIX_>: env name prefix for keys without a rename.
• --scope <scope>: production, preview, or both (default production).
• --key <KEY[=NEW_NAME]>: repeatable. Omit it to inject every key in the project.

A stack-level binding injects into every member. To give one member only part of a project, bind that member with --app and --key.

To change an existing binding, run bind again with --add-key or --remove-key. The command edits the binding in place, so the target never loses the binding during the change.

# add one key to the existing binding
$ reoclo secrets bind storage --app api --add-key S3_REGION

# remove one key from it
$ reoclo secrets bind storage --app api --remove-key S3_REGION

• --add-key <KEY[=NEW_NAME]>: repeatable. Adds the key. With =NEW_NAME it updates the rename of a selected key. Without it, a selected key keeps its rename.
• --remove-key <KEY>: repeatable. You cannot remove the last key, because an empty selection means every key. Unbind instead.

Running bind with --key on a project that is already bound replaces the selection in place. Use this to pin an explicit list on a binding that injects every key, because that binding has no selection for --add-key to edit.

bindings --app <app> or bindings --group <stack> lists the target’s bindings with their key selections. unbind <bindingId> --app|--group removes one; a unique id prefix is enough.

Bindings apply on the next deploy.

Exit codes

Code	Meaning
0	Success
1	Server-side error, or a provider CLI failed during import
2	Bad arguments: a missing set value, a projects update with no change, a projects create with an empty or duplicate name, a bad inject input path, a malformed op:// reference, or an existing inject output without -f
3	Authentication failure: you are not signed in, or the session expired
4	Not permitted: no access to the project, an automation key on a subcommand that needs a login session, or a provider token is missing
5	Project or key not found
6	An inject template reference did not resolve: the project is not granted, or the key does not exist
7	The control plane was unreachable (CLI 0.55.0+; earlier versions report 1)

Being signed out is 3. Being signed in without access to that project is 4. Run reoclo login for the first. Ask an admin for a grant for the second.

Related

• reoclo run: inject granted secrets into a command
• Secrets Manager: projects, versions, and access
• reoclo env: an application’s own environment variables