Project Configuration

Rise projects are configured through a rise.toml file in your project directory and through CLI flags.

rise.toml

The rise.toml file defines your project metadata and build settings. Both rise.toml and .rise.toml are supported — if both exist, rise.toml takes precedence (with a warning).

A JSON Schema is available for editor auto-completion and validation. To enable it in editors that support the Taplo TOML language server, add this comment as the first line of your rise.toml:

#:schema https://rise.example.com/docs/schemas/rise-toml-v1.schema.json

[project] Section

[project]
name = "my-app"

[project.env]
LOG_LEVEL = "info"

Field	Type	Description
name	String	Project name (used for URLs, registry paths, and as default for -p flag)
env	Object	Plain-text environment variables applied as deployment overrides (source: toml)

Keys starting with RISE_ are reserved for variables Rise injects into the workload and are rejected when rise.toml is loaded — in [project.env], [environments.<name>.env] and [containers.<name>.env] alike.

[build] Section

[build]
backend = "docker"
dockerfile = "Dockerfile.prod"
args = ["NODE_ENV=production", "BUILD_VERSION"]

Field	Type	Description
backend	String	Build backend: docker, docker:build, docker:buildx, buildctl, docker:buildctl, pack, railpack, railpack:buildctl
dockerfile	String	Path to Dockerfile, relative to rise.toml (default: Dockerfile or Containerfile)
build_context	String	Default build context path for Docker builds, relative to rise.toml
build_contexts	Object	Named build contexts for multi-stage Docker builds (format: { "name" = "path" })
builder	String	Buildpack builder image (pack backend only)
buildpacks	Array	Buildpacks to use (pack backend only)
args	Array	Build-time arguments (format: KEY=VALUE or KEY to read from shell). Alias: env for backward compat.
container_cli	String	Container CLI: docker or podman
managed_buildkit	Boolean	Enable/disable managed BuildKit daemon (auto-enables when SSL_CERT_FILE is set)
no_cache	Boolean	Disable build cache

[environments.<name>] Section

Define per-environment settings. Set default = true on one environment to auto-select it when deploying without --environment.

[environments.staging]
default = true
env.DATABASE_URL = "postgres://staging-db/mydb"
env.LOG_LEVEL = "debug"

[environments.production]
env.DATABASE_URL = "postgres://prod-db/mydb"

Field	Type	Description
default	Boolean	If true, this environment is used when --environment is not specified. At most one environment may be default.
env	Object	Plain-text environment variables scoped to this environment (applied as deployment overrides)

See Environment Variables for details.

Full Example

[project]
name = "my-app"

[project.env]
LOG_LEVEL = "info"
APP_MODE = "production"

[build]
backend = "pack"
builder = "heroku/builder:24"
buildpacks = ["heroku/nodejs", "heroku/procfile"]
args = ["BP_NODE_VERSION=20"]

[environments.staging]
default = true
env.DATABASE_URL = "postgres://staging-db/mydb"
env.LOG_LEVEL = "debug"

[environments.production]
env.DATABASE_URL = "postgres://prod-db/mydb"

Project Creation

# Create project on backend and write rise.toml
rise project create my-app

# Create project on backend only (no rise.toml written)
rise project create my-app --no-rise-toml

# If rise.toml already exists, the project name is read from it
rise project create

If a rise.toml already exists, it is never overwritten — the project is created on the backend using the name from the file.

Managing a Project

rise project show, update, and delete take an optional project name. When omitted, the name is read from the [project] section of rise.toml (or .rise.toml) in the directory given by --path (defaults to the current directory):

# Both work when rise.toml has [project] name = "my-app"
rise project show my-app
rise project show

Configuration Precedence

Settings are resolved in this order (highest to lowest priority):

1. CLI flags (e.g., --backend pack)
2. Project config file (rise.toml / .rise.toml)
3. Environment variables (e.g., RISE_CONTAINER_CLI, RISE_MANAGED_BUILDKIT)
4. Global config (~/.config/rise/config.json)
5. Auto-detection / defaults

For array fields (buildpacks, args), CLI values are appended to config file values rather than replacing them.

Global CLI Config

The CLI stores global configuration in ~/.config/rise/config.json, including:

• Backend URL
• Container CLI preference (docker or podman)
• Managed BuildKit setting

This file is created automatically on first rise login. Login tokens are stored separately under ~/.config/rise/credentials/, keyed by backend URL. URLs that differ only in trailing slashes share a credential. A URL without a saved token requires login or an explicit token source such as RISE_TOKEN.

Login Profiles

Profiles are local aliases for backend URLs. To give a backend a convenient name, log in with a named profile:

# Log in and register a new profile named "work" (created if it doesn't exist)
rise login --profile work --url https://rise.work.example.com

# Use it for a single command
rise project list --profile work

# ...or for a whole shell session
export RISE_PROFILE=work
rise project list

# Make it the default for future commands
rise profile use work

# See every registered profile and which one is active
rise profile list

# Remove the alias (the URL's saved login remains available)
rise profile remove work

Profiles pointing to the same URL share one login token. Logging in through any of those profiles updates that shared token. You can also use a URL directly, without creating a named profile:

rise login --url https://rise.example.com
RISE_URL=https://rise.example.com rise project list

--profile takes priority over RISE_PROFILE. rise login --url takes priority over RISE_URL; either URL override takes priority over the selected profile’s URL. Credentials always belong to the effective URL.

When no URL or profile override is set, Rise uses targets.default from the project configuration, then the profile selected by rise profile use, then the default profile’s URL, and finally http://localhost:3000. rise profile use default selects the default profile for future commands. Named profile settings are stored at ~/.config/rise/profiles/<name>.json; the default selection is stored at ~/.config/rise/default-profile.

Project Targets

The optional targets.default entry supplies a backend URL or a local profile name when no --profile, RISE_PROFILE, rise login --url, or RISE_URL override is set. Specify exactly one of url and profile:

[targets.default]
url = "https://rise.example.com"

To use a local profile instead:

[targets.default]
profile = "work"

A url target is chosen by whoever controls the repository, so the CLI sends it only the stored login for that URL. It refuses to send RISE_TOKEN, RISE_TOKEN_COMMAND or GitHub Actions OIDC tokens to it; in CI, set RISE_URL to the backend URL instead. A profile target resolves to a URL from your own configuration and has no such restriction.

A referenced profile must exist locally. The CLI reads rise.toml (or .rise.toml) from the command’s application directory: its --path or positional path when supported, otherwise the current directory. If the section or its default entry is absent, the configured global default applies. Profile management commands operate on local aliases independently of project targets.

Backend Configuration Schema

If you’re operating a Rise deployment, a JSON Schema for backend configuration (rise.yaml) is available in the operator docs at backend-settings.schema.json. See the Operator Configuration guide for details.