Your configuration. In your terminal.

Use Node.js 24 or newer. Install the public @keyrua/cli package with npm; Bun is not required.

npm install --global @keyrua/cli

To inspect the CLI without a global installation:

npx @keyrua/cli --help

Upgrade an existing installation when a new release is available:

npm install --global @keyrua/cli@latest

Open a terminal in your application's directory, then authenticate. Sign in in the browser and choose the organization that owns your project. If you do not have one yet, create it in the dashboard.

keyrua login

Return to the terminal after the browser completes login. If your browser does not open automatically, use the URL printed by the CLI. Keep this command running while you complete the browser step.

Login saves credentials in .keyrua.json in the current directory and adds that file to .gitignore. Log in and run subsequent commands from that same directory.

Copy your project's slug from the dashboard. This example uses my-app; replace it with your own slug. Initialization validates the project and saves the default environment.

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

Run keyrua init without flags for an interactive project and environment picker. Create a project in the dashboard first if the picker is empty.

Environments: LOCAL, TEST, DEVELOPMENT, STAGING, PRODUCTION. Names are case insensitive. Use --project and --env on a command to override the saved defaults. Environments organize configuration; organization membership governs access. Read the security model.

Keyrua fetches the selected environment and injects its values into the child process. It does not write a local .env file. Replace node server.js with your application's executable and arguments; keep -- before that command.

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

Fetched values override inherited environment variables with the same names. The app keeps using its ordinary environment variable access; no Keyrua SDK is needed. Later secret changes take effect when you run the command again.

Commands run as executables without a shell. On Windows, use an executable such as node; shell-only commands and batch wrappers need an explicit shell command.

Pull to a local file

Export the selected environment when your tooling needs a .env file. The output contains plaintext values. This command overwrites an existing output file; choose a separate path if you need to preserve local configuration, and keep the file out of Git.

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

Without --output, the CLI writes to .env.

Preview a push, then apply it

Import a local file into Keyrua. Start with a dry run to inspect how many secrets will be created, updated, deleted, or left unchanged. Values are not printed in this summary.

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

When the preview matches your intent, run the push and confirm the changes:

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

Push preserves remote keys missing from the file by default. --prune deletes those keys; with an empty file, it can delete the entire environment. Review a dry run before using it. --yes skips confirmation. New secrets are sensitive by default; --no-sensitive creates new values without KMS encryption. Never use that option for credentials.

Push rejects duplicate or invalid keys, empty values, and values larger than 256 KB. Quoted values are parsed using dotenv.

Find every command, argument, option, and default in the dedicated command reference. Keep this guide open for the end-to-end setup flow.

The CLI reads .keyrua.json from the current directory. It contains your token, organization, project slug, and default environment. It is a credential file: do not commit it, share it, or paste it into a support request. There is no global login config in your home directory.

For a different organization, run login again in that directory and choose the intended organization, then initialize its project. There is no --org flag.

By default, the CLI uses https://api.keyrua.dev and opens https://keyrua.dev. For local development or a preview, set KEYRUA_API_URL and KEYRUA_APP_URL in your project's .env file or shell before login. Point both to the same deployment. These example URLs contain no credentials; replace their ports or hosts with your own.

KEYRUA_API_URL="http://localhost:8080"
KEYRUA_APP_URL="http://localhost:3000"

Shell variables take precedence over the .env file. The CLI loads overrides from the current directory, so run it there consistently. Log in again when switching between local, preview, and production.

“keyrua: command not found” or a Node error

Check that Node.js is at least 24. Reopen your terminal after installing Node or updating PATH. Ensure npm's global executable directory is on PATH, or use the npx option above.

node --version

Missing login, wrong organization, or project not found

Run commands from the directory where you logged in. Check the current session below, then log in again to choose the right organization. Use the project's slug, rather than its display name, when linking the directory. Ask an organization administrator to invite you if you cannot select it.

keyrua whoami

Browser login times out or the API is unreachable

Start login again and complete the browser step promptly. Keep the terminal open and use its printed login URL if needed. Check network access, VPN or proxy settings, and any service URL overrides. A local setup needs both the web app and API running.

keyrua health

Still stuck? Contact Keyrua with the command, CLI version, operating system, and a redacted error. Do not include secret values or your .keyrua.json file.