Configure projects with Ory CLI

All Ory components use the same configuration format and APIs whether they are self-hosted or used through Ory Network.

This allows you to use the Ory CLI to configure your components, no matter how you use Ory!

Stored secrets

warning

When you read your Ory Network project configuration through the API or the Ory CLI (for example with ory get project or ory get identity-config), the following secret fields are returned empty even when a value is stored:

• SMTP courier.smtp.connection_uri — the password segment of the URI is removed.
• OIDC provider client_secret — for every entry in selfservice.methods.oidc.config.providers.
• Apple provider apple_private_key.

The stored value stays in place and continues to be used at runtime. Only the API response is redacted.

When you write the configuration back:

• To keep the stored secret: leave the field as the API returned it (null for OIDC client_secret and apple_private_key, or a URI without the password segment for SMTP connection_uri). The server merges your update with the existing secret.
• To rotate a secret: set the new value explicitly.
• Setting an OIDC client_secret or Apple apple_private_key to an empty string is rejected by configuration validation — these fields are required when the provider is configured, so you cannot accidentally clear them by sending an empty value. To remove a secret entirely, remove the provider.

Configure projects

There are two ways to adjust the configuration of projects. You can:

• overwrite / import configuration from a file using the ory update command
• patch the existing configuration using the ory patch command

Overwrite / import configuration

To overwrite the entire project configuration or to import a brand new config, create a file with the configuration you want to use.

The configuration format follows the updateProject API request payload.

note

The /services/identity/config key is compatible with the Ory Kratos configuration format except for some keys (for example serve, dsn) which are ignored.

{
  "services": {
    "identity": {
      "config": ...
    }
  }
}

Let's look at an example. If you want to change the name of the email sender for recovery and verification emails, create a configuration file that looks like this:

config.json

{
  "name": "My Project Name",
  "services": {
    "identity": {
      "config": {
        "courier": {
          "smtp": {
            "from_name": "My Custom E-Mail Name"
          }
        }
      }
    }
  }
}

Next, use the Ory CLI to apply the config:

ory update project --project <project-id> --workspace <workspace-id> --file config.json

Patch configuration

When you want to change specific parts of the configuration instead of overwriting the entire config, use the ory patch command.

Use this command in combination with JSON Patch to target individual keys.

To perform an update similar to the one described in the previous paragraph and change the name of the email sender for recovery and verification emails, run this command:

ory patch project --project <project-id> --workspace <workspace-id> \
  --replace '/services/identity/config/courier/smtp/from_name="My Custom E-Mail Name"'

Use the --replace flag to indicate the key you want to change.

tip

When patching configuration, the part after = is interpreted as raw JSON. Use this format to patch the desired data types:

• String: /path/to/key="my string"
• Boolean: /path/to/key=true
• Number: /path/to/key=123
• Complex: /path/to/key={"my": ["values", {"foo":"bar"}]}