First-time Controller setup

1. Retrieve the initial admin secret

Read InitialAdminSecretArn from your Controller bootstrap stack and ControllerEndpointUrl (or legacy JwtApiUrl) from your Controller foundation stack, then fetch the initial administrator secret from AWS Secrets Manager:

INITIAL_ADMIN_SECRET_ARN="$(aws cloudformation describe-stacks \
  --region us-east-1 \
  --stack-name rippflow-prod-controller-bootstrap-main \
  --query "Stacks[0].Outputs[?OutputKey=='InitialAdminSecretArn'].OutputValue" \
  --output text)"

aws cloudformation describe-stacks \
  --region us-east-1 \
  --stack-name rippflow-prod-controller-main \
  --query "Stacks[0].Outputs[?OutputKey=='ControllerEndpointUrl' || OutputKey=='JwtApiUrl' || OutputKey=='DeploymentId']"

aws secretsmanager get-secret-value \
  --region us-east-1 \
  --secret-id "$INITIAL_ADMIN_SECRET_ARN" \
  --query SecretString --output text | jq .

The Controller runtime never reads or exposes bootstrap secrets. If the temporary password expires before first login, reset it in Cognito with your AWS administrator role.

2. Sign in, replace password and review MFA status

• First-time controller login: Sign in as admin and replace the temporary password with at least 14 characters.
• MFA: TOTP/passkey enrollment and recovery-code escrow are not yet enabled on the default Cognito client. Enterprise OIDC installations enforce MFA through your identity provider.
• Invite operators: Create basic user accounts with rippflow users create or bind Enterprise SSO groups.

rippflow users create --username alice --email alice@acme.example --role readWrite --json
rippflow users list --limit 20 --json

3. Connect an installation

Use your installation’s HTTPS Controller URL, including its path prefix. Check Rippflow Studio’s CLI commands with rippflow --help.

Sign in from your terminal

On installations advertising browser login (1.8.2+), sign in and save the session in your OS credential store.

rippflow login --installation-url https://controller.example.com
rippflow auth status --json
rippflow whoami --json
rippflow installation compatibility --json

Check the identity returned by whoami and the release reported by installation compatibility. To switch installations, repeat login with the new URL. To remove a saved session, run rippflow logout --installation-url <controller-url>.

Use an access token

For installations on 1.0.x through 1.8.1, or when browser login is unavailable, set the installation URL and matching bearer token.

export RIPPFLOW_CONTROLLER_URL="https://controller.example.com"
export RIPPFLOW_ACCESS_TOKEN="<bearer-access-token>"
rippflow whoami --json

Connect CI with a machine identity

For installations on 1.10.0 or later using a direct Controller endpoint, exchange the registered client’s key for a short-lived machine token.

export RIPPFLOW_CONTROLLER_URL="https://controller.example.com"
export RIPPFLOW_MACHINE_TOKEN="$(rippflow auth machine-token \
  --installation-url "$RIPPFLOW_CONTROLLER_URL" \
  --client-id ci-deployer --private-key-file ./ci-ed25519.pem --raw)"
rippflow whoami --json

Anonymous local development

Build your first workflow offline without a Controller or login. To use bundled docs with an agent, Connect Your AI Agent →.