flowcy CLI

The flowcy CLI is the command-line companion to flowcy.dev's Secrets feature. Use it to pull decrypted secret files into a local directory — typically your project root or a CI workspace — without copying anything by hand.

The clever bit: the CLI itself never sees your encryption key. It opens a browser, the browser does the WebAuthn PRF + decryption, and the plaintext is delivered to the CLI over a one-shot loopback HTTP server.

Install

Download the CLI from code.rxlab.app.

Configure

The CLI authenticates to the rxlab identity provider as a public OAuth PKCE client. You need an OAuth client_id registered for the CLI, which you can set via:

1. An environment variable (highest precedence)
2. ${UserConfigDir}/flowcy/config.env (per-user file)
3. .env in your current working directory
4. Built-in defaults (lowest precedence)

The minimum is:

export FLOWCY_CLIENT_ID=autopilot-cli-prod

For a persistent setup, drop a config.env next to your other tool configs:

# macOS:    ~/Library/Application Support/flowcy/config.env
# Linux:    ~/.config/flowcy/config.env
# Windows:  %AppData%\flowcy\config.env
 
FLOWCY_CLIENT_ID=autopilot-cli-prod
FLOWCY_AUTH_ISSUER=https://auth.rxlab.app
FLOWCY_BASE_URL=https://flowcy.dev

Sign in

flowcy login

This runs OAuth 2.0 Authorization Code with PKCE:

1. The CLI binds a one-shot loopback HTTP server on a random port and generates a code verifier.
2. It opens your browser to the rxlab IdP sign-in page.
3. After you sign in, the IdP redirects back to http://127.0.0.1:<port>/callback with a code.
4. The CLI exchanges the code (with its PKCE verifier) for {access_token, refresh_token, id_token}.
5. Tokens are written to ${UserConfigDir}/flowcy/credentials.json with mode 0600. Refresh is automatic when within 60 seconds of expiry.

To sign out and revoke your refresh token:

flowcy logout

Interactive TUI

Just run:

flowcy

with no arguments. You get a Bubble Tea TUI that walks you through:

Sign in → Feature menu → Repository → Environment → Download (all files / single file)

Keys: ↑/↓ to move, Enter to select, Esc to go back, / to filter, q to quit.

The TUI is the recommended path day-to-day; subcommands below exist for scripting.

List repositories and environments

# List all secrets-enabled repositories you have access to.
flowcy secrets list
 
# List environments inside a specific repository.
flowcy secrets list owner/repo

If you run flowcy secrets list from inside a git working tree whose remote matches a known repository, that repo is highlighted as (current repo).

Download files

Pull every file in an environment to the current directory:

flowcy secrets download owner/repo --env dev

Common flags:

Examples:

# Pull only .env into ./.env.d, overwriting if needed.
flowcy secrets download owner/repo --env prod --file .env --out ./.env.d --force
 
# Allow up to 5 minutes for the browser flow if you're on a slow auth setup.
flowcy secrets download owner/repo --env staging --timeout 5m

How a download actually works

The CLI cannot perform WebAuthn PRF itself, so it brokers decryption through the browser you're already signed in to:

1. The CLI binds a one-shot HTTP server on 127.0.0.1:<random-port> and generates a 256-bit nonce.
2. It opens ${FLOWCY_BASE_URL}/dashboard/secrets/cli-decrypt?repo=…&env=…&port=…&nonce=… in your default browser.
3. The page (in your authenticated browser session) fetches the encrypted bundle, prompts your passkey for PRF, derives your KEK, unwraps the environment DEK, decrypts each file in-memory, and POSTs the plaintext to http://127.0.0.1:<port>/callback with the nonce.
4. The CLI verifies the nonce with constant-time comparison, writes each file under --out with mode 0600, and exits.

The browser tab tells you "Done — you can close this tab" when it's finished.

Security notes

• The local servers (login callback + decrypt callback) bind to 127.0.0.1 only and reject non-loopback connections.
• OAuth state and decrypt nonces are 32 bytes, single-use, and compared in constant time.
• id_token claims (nonce, iss, aud, exp) are verified locally; the token itself is fetched directly from the IdP's token endpoint over TLS (RFC 8252 §7).
• credentials.json is written with mode 0600; the CLI refuses to load it if the mode is laxer.
• Downloaded files are written with mode 0600 and the CLI refuses to overwrite existing files unless you pass --force. Filenames containing .. or starting with / are rejected.

Troubleshooting

"Passkey PRF unavailable" — your passkey or browser doesn't return a PRF result. Re-register the passkey on auth.rxlab.app with a PRF-capable authenticator (TouchID, FaceID, hardware key, 1Password, iCloud Keychain on iOS 17+).

Browser doesn't open — set BROWSER to your preferred command, or open the URL the CLI prints manually.

"You don't have a key for this environment" — someone with access to that environment needs to add you as a member from the Secrets dashboard before you can pull files.

CI usage — the CLI is interactive by design (it requires WebAuthn PRF), so it's not suitable for headless CI. For CI, fetch secrets through GitHub Actions encrypted secrets or a secrets manager that supports machine credentials. flowcy.dev Secrets is a developer-laptop and shared-environment tool.