Platform CLI
The Tenzir Platform CLI allows users to interact with the Tenzir Platform from the command-line to manage their workspaces and nodes.
Installation
Install the tenzir-platform
package from PyPI.
Authentication
Synopsis
tenzir-platform auth login
tenzir-platform workspace list
tenzir-platform workspace select <workspace_id>
Description
The tenzir-platform auth login
command authenticates the current user.
The tenzir-platform workspace list
and tenzir-platform workspace select
commands show workspaces available to the authenticated user and select one,
respectively.
<workspace_id>
The unique ID of the workspace, as shown in tenzir-platform workspace list
.
Manage Nodes
Synopsis
tenzir-platform node list
tenzir-platform node ping <node_id>
tenzir-platform node create [--name <node_name>]
tenzir-platform node delete <node_id>
tenzir-platform node run [--name <node_name>] [--image <container_image>]
Description
The following commands interact with the selected workspace. See Authentication above for how to select a workspace:
tenzir-platform node list
lists all nodes in the selected workspace, including their ID, name, and connection status.tenzir-platform node ping
pings the specified node.tenzir-platform node create
registers a new node at the platform so that it can be connected to the platform. Note that this neither starts a new node nor configures one, it just creates a new API key that a node can use to connect to the platform with.tenzir-platform node delete
removes a node from the platform. Note that this does not stop the node, it just removes it from the platform.tenzir-platform node run
creates and registers an ad-hoc node, and starts it on the local host. Requires Docker Compose to be available. The node is temporary and will be deleted when therun
command is stopped.
<node_id>
The unique ID of the node, as shown in tenzir-platform node list
.
<node_name>
The name of the node as shown in the app.
<container_image>
The Docker image to use for ad-hoc created node. We recommend using one of the following images:
tenzir/tenzir:v4.11.2
to use the specified release.tenzir/tenzir:latest
to use the last release.tenzir/tenzir:main
to use the currnet development version.
Manage Workspaces
This functionality of the CLI can only be used in combination with an on-premise platform deployment, which is available to users of the Sovereign Edition.
These CLI commands are only available to local platform administrators.
The TENZIR_PLATFORM_OIDC_ADMIN_RULES
variable described
here is used
to define who is an administrator in your platform deployment.
Synopsis
tenzir-platform admin list-global-workspaces
tenzir-platform admin create-workspace <owner_namespace> <owner_id> [--name <workspace_name>]
tenzir-platform admin delete-workspace <workspace_id>
Description
The tenzir-platform workspace admin list-global-workspaces
, tenzir-platform
admin create-workspace
, and tenzir-platform admin delete-workspace
commands
list, create, or delete workspaces, respectively.
<owner_namespace>
Either user
or organization
, depending on whether the workspace is
associated with a user or an organization.
The selected namespace will determine the default access rules for the workspace:
- For a user workspace, a single access rule will be created that allows
access to the user whose user id matches the given
owner_id
- For an organization workspace, no rules will be created by default and
they have to be manually added using the
add-auth-rule
subcommand described below.
<owner_id>
The unique ID of the workspace owner:
- If
<owner_namespace>
isuser
, then this matches the user'ssub
claim in the OIDC token. - If
<owner_namespace>
isorganization
, then this is an arbitrary string uniquely identifiying the organization the workspace belongs to.
--name <workspace_name>
The name of the workspace as shown in the app.
<workspace_id>
The unique ID of the workspace, as shown in tenzir-platform workspace list
or
tenzir-platform admin list-global-workspaces
.
Configure Access Rules
This functionality of the CLI can only be used in combination with an on-premise platform deployment, which is available to users of the Sovereign Edition.
These CLI commands are only available to local platform administrators.
The TENZIR_PLATFORM_OIDC_ADMIN_RULES
variable described
here is used
to define who is an administrator in your platform deployment.
Synopsis
tenzir-platform admin list-auth-rules <workspace_id>
tenzir-platform admin add-auth-rule [--dry-run]
email-domain <workspace_id> <connection> <domain>
tenzir-platform admin add-auth-rule [--dry-run]
organization-membership <workspace_id> <connection> <organization_claim> <organization>
tenzir-platform admin add-auth-rule [--dry-run]
organization-role <workspace_id> <connection> <roles_claim> <role> <organization_claim> <organization>
tenzir-platform admin add-auth-rule [--dry-run]
user <workspace_id> <user_id>
tenzir-platform admin delete-auth-rule <workspace_id> <auth_rule_index>
Description
Users with admin permissions can additionally use the tenzir-platform admin
list-auth-rules
, tenzir-platform admin add-auth-rule
, and tenzir-platform
admin delete-auth-rule
commands to list, create, or delete authentication rules
for all users, respectively.
Authentication rules allow users to access the workspace with the provided
<workspace_id>
if the user's id_token
matches the configured rule. Users
have access to a workspace if any configured rule allows access. The following
rules exist:
Email Suffix Rule:
tenzir-platform admin add-auth-rule email-domain
allows access if theid_token
contains a fieldconnection
that exactly matches the provided<connection>
and a fieldemail
that ends with the configured<domain>
.Organization Membership:
tenzir-platform admin add-auth-rule organization-membership
allows access if theid_token
contains a fieldconnection
that exactly matches the provided<connection>
and a field<organization_claim>
that exactly matches the provided<organization>
.Note that the
<organization_claim>
and<organization>
can be freely chosen, so this rule can also be repurposed for generic claims that are not necessarily related to organizations.Organization Role Rule:
tenzir-platform admin add-auth-rule organization-role
allows access if theid_token
contains a fieldconnection
that exactly matches the provided<connection>
, a field<organization_claim>
that exactly matches the provided<organization>
, and a field<roles_claim>
that must be a list containing a value exactly matching<role>
.We recommend using organization role rules to check if a user has a specific role with an organization.
User Rule:
tenzir-platform admin add-auth-rule user
allows access if theid_token
contains a fieldsub
that exactly matches the provided<user_id>
.