DOCS / COMMAND REFERENCE

Every command. Every option.

Look up syntax, arguments, aliases, and defaults. Start with the setup guide when you're connecting your first project.

Reference for @keyrua/cli v1.0.1 · Node.js 24+

Jump to a command

Global options and help

Put global options before the command. For example, use keyrua --json projects list for structured output.

Global CLI options
Option	Description	Default
`-V, --version`	Display the installed CLI version without executing a command.	—
`--json`	Request JSON results for health, whoami, logs, projects, secrets, and environments list. Place this flag before the command: keyrua --json secrets list. Login, init, and run retain their normal output; confirmation prompts still apply.	false
`-h, --help`	Display root help. Also available on every command and command group. Use keyrua help [command] for the built-in help command.	—

keyrua --help
keyrua secrets push --help

The installed version's help is the authority when upgrading. Commands read .keyrua.json from the current directory; project and environment flags override saved defaults where supported.

For installation, browser login, public service URL configuration, and troubleshooting, follow the setup guide.

Setup and workflows

keyrua health

Check connectivity to the configured Keyrua API.

keyrua health [options]

Options

health options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

Does not require login. Sends a request to the configured API's root endpoint.
KEYRUA_API_URL can override the default API URL through your shell or the current directory's .env file.

keyrua health

keyrua --json health

Authenticate in your browser and choose an organization.

keyrua login [options]

Options

login options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

Run from your application's directory. Login stores credentials in .keyrua.json there and adds that file to .gitignore; do not share or commit it.
Keep the terminal open while completing the browser step. If the browser does not open, follow the printed URL.
To change organizations, log in again and choose the intended organization. There is no --org flag.
The global --json flag does not make browser login non-interactive or change its success output to JSON.

keyrua login

keyrua whoami

Show the locally stored user, organization, expiry, and project configuration.

keyrua whoami [options]

Options

whoami options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

Requires a token in this directory's .keyrua.json. Reads the stored token's claims locally; it does not contact the API or verify current access or token validity.
JSON output includes userId, fullName, orgId, orgName, expires (Unix milliseconds), project, and environment.

keyrua whoami

keyrua --json whoami

keyrua init

Link this directory to a project and save its default environment.

keyrua init [options]

Options

init options
Option	Description	Default
`-p, --project <slug>`	Validate and select this project slug without showing the project picker.	Interactive project picker
`-e, --env <environment>`	Save this default environment without showing the environment picker. Valid environments are LOCAL, TEST, DEVELOPMENT, STAGING, and PRODUCTION; names are case insensitive.	Interactive picker; DEVELOPMENT preselected
`-h, --help`	Display help for this command without executing it.	—

Requires login. Without --project, the picker requests up to 100 projects from the logged-in organization.
Writes project and environment to the current directory's .keyrua.json while preserving its credentials, and adds the file to .gitignore.
The global --json flag does not remove pickers or make the final setup output JSON. Supply both flags to skip the pickers.

keyrua init

keyrua init --project my-app --env development

keyrua run

Fetch secrets and start a child process with those environment variables.

keyrua run [options] <args...>

Arguments

run arguments
Argument	Required	Description
`args...`	Yes	The executable and its arguments. Put -- before them to pass subsequent flags to the child process.

Options

run options
Option	Description	Default
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`-p, --project <slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, and an environment. Put Keyrua flags before --; arguments after it belong to your application.
Fetches the plaintext .env export, parses it with dotenv, and injects values without writing a local .env file. Fetched values override inherited variables with matching names.
The child runs with inherited input/output and without shell interpolation. Invoke a shell explicitly for shell-only syntax or wrappers; an executable such as node works directly.
The child process's exit code or terminating signal is propagated. The global --json flag does not transform application output into JSON.

keyrua run --project my-app --env development -- node server.js

keyrua run --env staging -- node server.js --port 4000

keyrua logs

List secret change records for a project and environment.

keyrua logs [options]

Options

logs options
Option	Description	Default
`-p, --project <slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`--take <n>`	Number of log entries to request.	20
`--skip <n>`	Number of records to skip. When omitted, the CLI leaves this parameter to the API.	API default: 0
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, and an environment. Records contain action, key, actor, and timestamp; they do not contain previous secret values.
Pagination is explicit; the CLI does not fetch additional pages automatically. Current API pagination accepts take from 1 to 100 and skip from 0 to 100.

keyrua logs --project my-app --env development

keyrua --json logs --env production --take 50 --skip 20

Projects

Manage projects in the organization chosen during login.

projects group options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

keyrua projects list

List projects in the organization selected during login.

keyrua projects list [options]

Options

projects list options
Option	Description	Default
`--take <count>`	Number of records to request. When omitted, the CLI leaves this parameter to the API.	API default: 100
`--skip <count>`	Number of records to skip. When omitted, the CLI leaves this parameter to the API.	API default: 0
`-h, --help`	Display help for this command without executing it.	—

Requires login and an organization, but not a linked project or environment.
The CLI has no pagination defaults of its own and does not fetch additional pages automatically. Current API defaults are take=100 and skip=0, with take from 1 to 100 and skip from 0 to 100.

keyrua projects list

keyrua --json projects list --take 20 --skip 20

keyrua projects get

Get details for one project in your logged-in organization.

keyrua projects get [options] <slug>

Arguments

projects get arguments
Argument	Required	Description
`slug`	Yes	The project's slug, not its display name.

Options

projects get options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

Requires login and an organization. No --project or --env flag is available; the required slug selects the project.

keyrua projects get my-app

keyrua --json projects get my-app

keyrua projects create

Create a project in the organization selected during login.

keyrua projects create [options] <name>

Arguments

projects create arguments
Argument	Required	Description
`name`	Yes	Display name for the new project. Quote names containing spaces.

Options

projects create options
Option	Description	Default
`-d, --description <text>`	Optional description for the new project.	—
`-h, --help`	Display help for this command without executing it.	—

Requires login and an organization. The API creates the slug and enforces your plan's project limit.
Creating a project does not link this directory to it. Run keyrua init with its returned slug afterward.

keyrua projects create "Demo app"

keyrua projects create "Demo app" --description "Example backend service"

keyrua projects delete

Permanently delete a project and its secrets across all environments.

keyrua projects delete [options] <slug>

Arguments

projects delete arguments
Argument	Required	Description
`slug`	Yes	Slug of the project to delete.

Options

projects delete options
Option	Description	Default
`-y, --yes`	Skip the confirmation prompt and apply the operation.	false
`-h, --help`	Display help for this command without executing it.	—

Requires login and organization administrator access. Deletion also removes the project's change records.
By default, you must type the project's exact slug to confirm. --yes skips that prompt; --json alone does not.

keyrua projects delete disposable-demo

keyrua projects delete disposable-demo --yes

Secrets

List, reveal, create, update, delete, import, and export secrets.

secrets group options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

keyrua secrets list

List secret metadata without revealing secret values.

keyrua secrets list [options]

Options

secrets list options
Option	Description	Default
`-p, --project <slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`--take <n>`	Number of records to request. When omitted, the CLI leaves this parameter to the API.	API default: 100
`--skip <n>`	Number of records to skip. When omitted, the CLI leaves this parameter to the API.	API default: 0
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, and an environment. Normal output shows key, sensitivity, and updated time; JSON returns the paginated metadata response without values.
The CLI has no pagination defaults of its own and does not fetch additional pages automatically. Current API defaults are take=100 and skip=0, with take from 1 to 100 and skip from 0 to 100.

keyrua secrets list --project my-app --env development

keyrua --json secrets list --take 20 --skip 20

keyrua secrets get

Reveal one secret's plaintext value and metadata.

keyrua secrets get [options] <key>

Arguments

secrets get arguments
Argument	Required	Description
`key`	Yes	Key of the secret to retrieve.

Options

secrets get options
Option	Description	Default
`-p, --project <slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, and an environment. This explicitly retrieves and prints plaintext, including for sensitive secrets.
Normal stdout is human-readable output containing the value and metadata. --json writes the returned secret object, including value, to stdout. There is no --stdout, --raw, or value-only output flag.

keyrua secrets get DEMO_BASE_URL --env development

keyrua --json secrets get DEMO_BASE_URL

keyrua secrets set

Create a secret or update an existing secret's value and metadata.

keyrua secrets set [options] <key> [value]

Arguments

secrets set arguments
Argument	Required	Description
`key`	Yes	Key of the secret to create or update.
`value`	No	The value. Required unless --stdin is used; positional values may enter shell history.

Options

secrets set options
Option	Description	Default
`-p, --project <slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`--stdin`	Read the value from standard input instead of [value]. Trailing whitespace is removed.	false
`--sensitive`	Mark the secret sensitive. Applied to creates and updates.	true
`--no-sensitive`	Mark the secret non-sensitive. Such values are stored without KMS encryption.	—
`--type <type>`	Secret type: STRING, BOOLEAN, or NUMBER. Type names are case insensitive.	STRING
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, and an environment. An existing key is updated; a missing key is created.
The defaults sensitive=true and type=STRING are sent on updates too. Pass the desired flags when updating an existing non-sensitive or non-string secret.
With --stdin, input is read until the stream closes, trailing whitespace is trimmed, and any positional [value] is ignored.
The API validates keys and values. Keys accept letters, digits, dots, underscores, and hyphens, up to 255 characters.

keyrua secrets set DEMO_BASE_URL https://example.invalid --no-sensitive

keyrua secrets set DEMO_FEATURE_ENABLED true --type BOOLEAN --no-sensitive

printf '%s' 'example-only-not-a-real-credential' | keyrua secrets set DEMO_API_KEY --stdin --sensitive

keyrua secrets delete

Delete one secret from a project and environment.

keyrua secrets delete [options] <key>

Arguments

secrets delete arguments
Argument	Required	Description
`key`	Yes	Key of the secret to delete.

Options

secrets delete options
Option	Description	Default
`-p, --project <slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`-y, --yes`	Skip the confirmation prompt and apply the operation.	false
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, an environment, and write access. Prompts for confirmation by default; declining cancels the deletion.
--yes skips the prompt. The global --json flag alone does not skip confirmation.

keyrua secrets delete DEMO_TEMP_KEY --env development

keyrua secrets delete DEMO_TEMP_KEY --env development --yes

keyrua secrets pull

Export an environment's plaintext secrets to a local .env file.

keyrua secrets pull [options]

Options

secrets pull options
Option	Description	Default
`-p, --project <project-slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <environment>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`--output <path>`	Output file path, resolved relative to the current directory. An existing file is overwritten.	.env
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, and an environment. Export includes plaintext secret values; protect the output file and keep it out of Git.
There is no stdout export flag. --json still writes the file and returns file, count, and environment metadata.
If the API export is empty, the CLI does not create or overwrite the file; an existing file remains untouched.

keyrua secrets pull --project my-app --env development --output .env.local

keyrua --json secrets pull --env staging --output .env.staging

keyrua secrets push

Preview and apply values from a local .env file to an environment.

keyrua secrets push [options]

Options

secrets push options
Option	Description	Default
`-f, --file <path>`	Local .env file to read, resolved relative to the current directory.	.env
`-p, --project <project-slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-e, --env <env>`	Environment. Overrides the saved environment. Accepts LOCAL, TEST, DEVELOPMENT, STAGING, or PRODUCTION, case insensitively.	Saved environment
`--prune`	Delete remote keys that are absent from the local file. An empty file can delete the whole environment.	false
`--no-sensitive`	Create new secrets without KMS encryption. Existing secrets retain their sensitivity.	New secrets are sensitive
`--dry-run`	Request a change preview from the API and stop without applying it.	false
`-y, --yes`	Skip the confirmation prompt and apply the operation.	false
`-h, --help`	Display help for this command without executing it.	—

Requires login, a project, an environment, and write access. Parses the file with dotenv and checks the remote diff before requesting confirmation and applying changes.
By default, missing remote keys are preserved. Review --prune with --dry-run before applying it; --yes skips confirmation but not the preview request.
New entries use type STRING and are sensitive by default. --no-sensitive only affects new entries; existing entries keep their type and sensitivity when their values change.
Duplicate or invalid keys, empty values, and values larger than 256 KB are rejected before synchronization. Keys can contain letters, digits, dots, underscores, and hyphens and must be at most 255 characters.
JSON output reports created, updated, deleted, unchanged, and total counts; it does not print values. --json alone does not remove confirmation prompts.
An empty file without --prune does nothing. With --prune, it can delete every remote key after confirmation.

keyrua secrets push --project my-app --env development --file .env.local --dry-run

keyrua secrets push --project my-app --env development --file .env.local

keyrua secrets push --project my-app --env development --file .env.local --dry-run --prune

Environments

List the supported environments for a configured project.

environments group options
Option	Description	Default
`-h, --help`	Display help for this command without executing it.	—

keyrua environments list

List the five supported environments for a configured project.

keyrua environments list [options]

Options

environments list options
Option	Description	Default
`--project <project-slug>`	Project slug. Overrides the project saved in this directory's .keyrua.json.	Saved project
`-h, --help`	Display help for this command without executing it.	—

Requires a locally stored token, organization, and project. Lists LOCAL, TEST, DEVELOPMENT, STAGING, and PRODUCTION from the CLI; it does not fetch project details or verify project access with the API.
Only the long --project flag is available here. There is no -p, --env, or environment creation command.

keyrua environments list --project my-app

keyrua --json environments list --project my-app