Environment commands in the Permit CLI
Create, copy, and delete Permit.io environments, invite members, and export an environment as Terraform code with the permit env commands. This reference is for developers and platform engineers who manage environments from a terminal or a CI/CD pipeline.
Before you use these commands, install the Permit CLI and sign in with permit login. See Install and use the Permit CLI. Each command also accepts --api-key instead of the stored credentials. When a flag the command needs is missing, the CLI prompts you for it.
Manage environments
permit env create
permit env create creates an environment in the project of your credentials.
| Flag | Alias | Description |
|---|---|---|
--name <string> | -n | The environment name. The CLI prompts for it when missing. |
--env-key <string> | -e | The environment key. |
--description <string> | -d | The environment description. |
--custom-branch-name <string> | -b | The Git branch name of the environment for GitOps. |
--jwks <string> | -j | The JSON Web Key Set (JWKS) for frontend sign-in, as JSON. |
--settings <string> | -s | The environment settings, as JSON. |
--api-key <string> | -k | The API key to create the environment with. |
Create a staging environment. Replace permit_key with a project API key:
$ permit env create --api-key permit_key --name "Staging" --description "Staging environment for testing"
Create an environment with every option:
$ permit env create --api-key permit_key --name "Development" --env-key "dev" --description "Dev environment" --custom-branch-name "dev-branch" --jwks '{"ttl": 3600}' --settings '{"debug": true}'
To confirm, open the Projects page in the Permit dashboard. The project lists the new environment.
permit env copy
permit env copy copies the policy of one environment to a new environment or to an existing environment. Use it in a CI/CD pipeline to test policy changes in a copy of an environment before you apply them to production.
| Flag | Default | Description |
|---|---|---|
--from <string> | Prompt | The ID or key of the environment to copy from. |
--to <string> | None | The ID or key of an existing environment to copy to. When set, the CLI ignores --name and --description. |
--name <string> | Prompt | The name of a new environment to copy to. |
--description <string> | Prompt | The description of the new environment. |
--conflict-strategy <fail | overwrite> | fail | What to do when an object exists in both environments: stop with an error, or overwrite the object in the target environment. Applies only with --to. |
--api-key <string> | Selection prompt | A project or organization API key. An environment API key can't copy environments. |
Copy the staging environment into the existing production environment, and overwrite conflicting objects:
$ permit env copy --api-key permit_key --from staging --to production --conflict-strategy overwrite
permit env delete
permit env delete deletes an environment.
After permit env delete deletes an environment, you can't restore the environment or anything in it. With --force, the command deletes the environment without asking for confirmation.
| Flag | Alias | Default | Description |
|---|---|---|---|
--env-id <string> | -e | Prompt | The ID of the environment to delete. |
--force | -f | false | Skips the confirmation prompt. |
--api-key <string> | -k | Stored credentials | The API key to delete the environment with. |
Delete the environment env_456:
$ permit env delete --api-key permit_key --env-id env_456
Delete the environment without the confirmation prompt:
$ permit env delete --api-key permit_key --env-id env_456 --force
permit env member
permit env member invites a member of your team to an environment with an environment role. Use it in a CI/CD pipeline after you create an environment, to give the team access.
| Flag | Default | Description |
|---|---|---|
--email <string> | Prompt | The email address of the member to invite. |
--role <admin | write | read> | Prompt | The environment role of the member. |
--project <string> | Prompt | The ID of the project. |
--environment <string> | Prompt | The ID of the environment. |
--inviter-email <string> | None | The email address of the person who sends the invite. |
--inviter-name <string> | None | The name of the person who sends the invite. |
--api-key <string> | Selection prompt | A project or organization API key. An environment API key can't invite members. |
Invite a member to the staging environment:
$ permit env member --api-key permit_key --environment staging --project my-project --email gabriel@permit.io --role admin
permit env select
permit env select changes the active environment that later commands run against, without signing out.
| Flag | Default | Description |
|---|---|---|
--api-key <string> | Browser sign-in | A project or organization API key. Without it, the CLI opens the browser to sign in. |
$ permit env select --api-key permit_key
Export an environment to Terraform
permit env export terraform
permit env export terraform exports the active environment as a Terraform HCL file for the Permit Terraform provider. Use it to start managing an environment with Terraform after you configured it in the Permit dashboard or with the API. The file includes resources, roles, relations, role derivations, user attributes, user sets, resource sets, and condition sets.
| Flag | Alias | Default | Description |
|---|---|---|---|
--file <string> | -f | Print to the terminal | The path of the HCL file to write. |
--api-key <string> | -k | Stored credentials | The API key of the environment to export. |
Export an environment with an API key to permit-config.tf:
$ permit env export terraform --api-key permit_key --file permit-config.tf
Export the environment you signed in to:
$ permit env export terraform --file permit-config.tf
Print the HCL to the terminal:
$ permit env export terraform
To confirm, open the exported file. The file starts with a terraform block that requires the Permit provider, and has a permitio_resource block for each resource in the environment. To apply the file, see Terraform provider.