Enable a role for CLI use
Enable a role for CLI use
The Simetrik CLI operates against your workspace through the platform API, so what you can do is governed by your workspace role — not by the CLI itself. This applies equally to a person running commands and to a Claude agent acting on their behalf.
This page is the complete model: how CLI access works, how an administrator grants the Use CLI permission (two paths), how a role gets assigned per workspace, and which per-operation grants each command needs.
Granting the permission is an administrator task. It's done by someone with access to Account administration (an account or security administrator). If you don't see the administration area, you're not the right person to do this — see Not an administrator? below.
How CLI access works: two layers
CLI access has two layers, and both must hold before you can operate the CLI:
- Workspace gate — your workspace must have CLI access enabled (
cli.access). - Role permission — your assigned role must carry the Use CLI permission.
Layer 1 · Workspace gate
Before any command runs, the CLI checks whether your workspace has CLI access enabled (cli.access). If it doesn't, every command fails with:
CLI access is not available for your workspace. Contact your administrator.If you see this (error code CLI_ACCESS_DENIED), your workspace administrator must enable CLI access for your account.
Layer 2 · Role permission (Use CLI)
Even with the workspace gate open, you can only operate the CLI if your role grants the Use CLI permission (under the role's Developer category). The permission is a single switch:
Account administration (Administración) → choose the account → Roles → open or create a role → Developer (Desarrollador) category → Use CLI (Usar CLI)
Use CLI is the only role permission strictly required to operate the CLI. It does not widen what the CLI can do — every other action still obeys the role's normal permissions (creating sources, configuring reconciliations, viewing data, and so on — see Permissions by operation). If your role is missing it, commands fail with a permission / access-denied error instead of running. Without Use CLI checked, the person cannot operate the CLI at all, even after installing it.
A Claude agent acting on your behalf runs under your role — so it needs the same Use CLI permission you do. There is no separate agent permission.
Which layer is blocking me?
CLI_ACCESS_DENIED→ the workspace isn't enabled for the CLI. Ask an admin to enable CLI access for the workspace (Layer 1).- Any other permission / access-denied error → your role is missing a grant. Ask an admin to check your role, starting with the Use CLI permission (Layer 2) and then the per-operation grants below.
Get the permission: two paths
When someone is assigned to a workspace, they're assigned a role. Simetrik's built-in system roles ship with Use CLI turned off, and system roles can't be edited — you can't just open one and flip the switch. There are two ways to get the permission onto someone's role:
Option A · Assign the Supervisor CLI system role
Supervisor CLI is a system role with the same permissions as the system role Supervisor, plus Use CLI already turned on. If the person's access profile matches Supervisor, assigning this role is the fastest path — no role creation needed.
Option B · Create a custom role with Use CLI enabled
If no system role fits, create a custom role — either by duplicating an existing system role or starting from scratch — and turn on Use CLI yourself:
Open Roles for the account
In Account administration (the gear icon, bottom-left), select the account you're working in, then open Roles. You'll see the predefined and custom roles.
The Roles screen lists predefined and custom roles, with a "Create new role" button at the top right.
Turn on Use CLI under Developer
Open an existing custom role, duplicate a system role, or create a new one from scratch (for example, CLI enabled). In the category list on the left, scroll to Developer (Desarrollador) and check Use CLI (Usar CLI). The Developer counter goes from 0/1 to 1/1.
The Developer category selected, with the "Use CLI" checkbox now ticked (1/1).
Set the rest of the role's permissions to match what each person should be able to do on the platform — the CLI respects those same permissions.
Name and save the role
Give the role a clear name (e.g. CLI enabled) and a short description, then Save changes.
Assign the role in each workspace
Enabling the permission on a role (Option A or B) does nothing until that role is assigned. Assignment is per person, per workspace — the role is created once, but you assign it in each workspace where the person works.
Open the workspace
From the account menu, go to Workspaces (Espacios de trabajo) and open the workspace where the people are (use the search box to find it).
Set each person's role
Inside the workspace, open Users (Usuarios). For each person who needs the CLI, use the Role (Rol) dropdown and select Supervisor CLI or the custom role you enabled. Repeat for every teammate who needs CLI access.
If someone belongs to more than one workspace, they need the role in the specific workspace they log into (simetrik login --workspace <id>). The permission is checked against the workspace of the active session.
Log in: the workspace picker filters by Use CLI
simetrik login authenticates you into a specific workspace. If you belong to several, the CLI prompts you to pick one — and only lists the workspaces where your role has Use CLI enabled — or you can skip the prompt with --workspace <id>. Your role in that workspace then determines which operations are allowed.
Permissions by operation
Once both access layers are satisfied (the workspace gate and the Use CLI role permission), individual commands are still governed by the role's per-operation grants. These apply within your role — on top of the two access layers, they don't replace them. Each command maps to an entity + action permission, and you need the matching grant in your role:
| What you want to do | Requires (entity · action) |
|---|---|
| Create or edit a source | resources · create_edit |
| Create or edit a reconciliation | reconciliations · create_edit_configure |
| View a reconciliation's data & configuration | reconciliations · view_data_configurations |
| Run a reconciliation | reconciliations · execute |
If a command returns a permission error, ask your administrator to grant the corresponding access for your role. Roles, permissions, and users are managed in app.simetrik.com — see What the CLI can't do.
After enabling it
The change takes effect on the person's next command — permissions are evaluated server-side on every call. If they were already logged in and are still blocked, have them run simetrik login again to refresh the local access cache. Because denials are never cached, granting access takes effect on the next command; revoking access may take a moment to apply while a short local cache of a prior grant expires.
Not an administrator?
If you're the person who needs the CLI but you don't have administration access, you can't enable this yourself. Ask your account or security administrator to:
- Assign the Supervisor CLI system role, or enable Use CLI (Usar CLI) on a custom role (under the Developer category), and
- Assign that role to you in the workspace you log into.
Point them to this page — it's the whole procedure.
Next: First use: login to authenticate once the role is in place.