Skip to main content

Common Workflows

Multi-command playbooks for typical octo-cli usage scenarios. Each step has its own copyable code block — paste them one at a time. Full per-command documentation is in the Command Reference sidebar section.

Initial Setup​

  1. Configure endpoints:

    octo-cli -c Config `
      -isu "https://localhost:5003/" `
      -asu "https://localhost:5001/" `
      -tid "meshtest"

  2. Login:

    octo-cli -c LogIn -i

  3. Create tenant:

    octo-cli -c Create -tid "myproject" -db "myproject_db"

  4. Grant yourself access to the new tenant:

    octo-cli -c ProvisionCurrentUser -ttid "myproject"

  5. Switch to new tenant context:

    octo-cli -c Config -tid "myproject" -isu "https://localhost:5003/"
    octo-cli -c LogIn -i

  6. Import construction kit:

    octo-cli -c ImportCk -f "./my-model.yaml" -w

See Tenant Lifecycle for detailed guidance on creating, attaching, and restoring tenants.

Manage Contexts​

Contexts work like kubectl contexts — each one bundles its own service URIs, tenant ID, and stored access/refresh token. Switching contexts is how you target different environments (dev / prod / customer-X) without reconfiguring everything. They live in ~/.octo-cli/contexts.json.

CommandDescription
AddContextAdd or update a named context
UseContextSwitch the active context
ListContextsList all contexts, or show details of one
RemoveContextRemove a context

  1. Add a new context (with all relevant service URIs):

    octo-cli -c AddContext -n staging-1_meshtest `
      -isu https://connect.staging.octo-mesh.com/ `
      -asu https://assets.staging.octo-mesh.com/ `
      -bsu https://bots.staging.octo-mesh.com/ `
      -csu https://communication.staging.octo-mesh.com/ `
      -tid meshtest

    The first context added is automatically activated. Subsequent AddContext calls update if the name already exists. See the AddContext reference page for the full list of service-URI flags.

  2. List contexts and inspect details:

    Tabular list of all contexts — the active one is marked with *:

    octo-cli -c ListContexts

    Detail view of a single context — shows all service URIs and auth status:

    octo-cli -c ListContexts -n staging-1_meshtest

    JSON output for scripting (jq, ConvertFrom-Json, etc.):

    octo-cli -c ListContexts -j

    The Auth column reports one of: no token (run LogIn), authenticated (expires <timestamp>[, refresh available]), or expired (expires <timestamp>). Access and refresh tokens are never written to the output, only the expiry timestamp and a hasRefreshToken flag (in JSON mode).

  3. Switch the active context — all subsequent commands target this context's tenant and services:

    octo-cli -c UseContext -n staging-1_meshtest

  4. Remove a context when no longer needed (does not affect the remote service):

    octo-cli -c RemoveContext -n old-context

    If the removed context was active, another context becomes active automatically (or none if it was the last).

Context selection is the prerequisite for LogInClientCredentials (see Non-Interactive Authentication below) — that command does not accept -tid; it reads the tenant from the active context.

Add Web Application Client​

  1. Create client:

    octo-cli -c AddAuthorizationCodeClient `
      -id "my-webapp" `
      -n "My Web App" `
      -u "https://myapp.com/" `
      -ru "https://myapp.com/auth/callback"

  2. Add required scopes:

    octo-cli -c AddScopeToClient -id "my-webapp" -n "assetSystemAPI.full_access"
    octo-cli -c AddScopeToClient -id "my-webapp" -n "identityAPI.full_access"

Set Up Group-Based Access​

  1. Create a group with roles:

    octo-cli -c CreateGroup `
      -n "Operators" `
      -d "Operations team" `
      -rids "DashboardViewer,ReportingViewer"

  2. Add users to the group:

    octo-cli -c AddUserToGroup -id "<group-rtid>" -uid "<user-id>"

  3. Optionally set up automatic assignment by email domain:

    octo-cli -c CreateEmailDomainGroupRule `
      -edp "company.com" `
      -tgid "<group-rtid>" `
      -d "Auto-assign company employees"

Give a Machine-to-Machine Client a Role​

Lets a client_credentials client call role-protected endpoints — its access token then carries the resolved role claims (direct + group-inherited), in the same shape as a user token.

  1. Assign a role directly to the client:

    octo-cli -c AddClientToRole -id "ci-deploy" -r "DataAnalyst"

  2. Or — recommended — add the client to a role-bearing group (by the client's runtime ID, from GetClient):

    octo-cli -c AddClientToGroup -id "<group-rtid>" -cid "<client-rtid>"

  3. Replace the full set of directly-assigned roles (by role id):

    octo-cli -c UpdateClientRoles -id "ci-deploy" -rids "<role-id-1>,<role-id-2>"

The client's next client_credentials token includes the resolved roles automatically.

Set Up Cross-Tenant Access​

In the child tenant: add OctoTenant provider pointing to parent, then create user mappings.

  1. Switch to the child tenant context:

    octo-cli -c Config -tid "child-tenant" -isu "https://id.example.com/"
    octo-cli -c LogIn -i

  2. Add OctoTenant identity provider:

    octo-cli -c AddOctoTenantIdentityProvider `
      -n "Parent Auth" `
      -ptid "octosystem" `
      -e true

  3. Create user mappings:

    octo-cli -c CreateExternalTenantUserMapping `
      -stid "octosystem" `
      -suid "<user-id>" `
      -sun "alice" `
      -rids "Development,DashboardViewer"

See Cross-Tenant Authentication for details.

Non-Interactive Authentication​

Set up client_credentials authentication for any unattended caller — a CI pipeline, a cron job, a systemd service, a container entrypoint, a remote-administration script, etc. Run the setup steps once from a workstation; the runtime steps execute on each invocation of the script or job.

One-time Setup (Workstation)​

  1. Authenticate as a user with permission to create clients in the target tenant:

    octo-cli -c UseContext -n prod
    octo-cli -c LogIn -i

  2. Create a client_credentials client in that tenant:

    octo-cli -c AddClientCredentialsClient `
      -id "my-script-client" `
      -n "Headless script client" `
      -s "<generated-secret>"

  3. Store the client ID + secret in a secrets manager — Azure DevOps variable group, GitHub Actions secret, Vault, AWS Secrets Manager, a private file readable only by the running user, etc.

On Each Script / Job Run​

  1. Pin the context so the tenant is correct:

    octo-cli -c UseContext -n prod

  2. Export credentials from wherever they're stored:

    $env:OCTO_CLI_CLIENT_ID    = "<from secret store>"
    $env:OCTO_CLI_CLIENT_SECRET = "<from secret store>"

  3. Login — tokens auto-renew while the env vars remain in scope, so a long-running script does not need to call LogInClientCredentials again between commands:

    octo-cli -c LogInClientCredentials

  4. Run any subsequent commands:

    octo-cli -c GetUsers
    octo-cli -c ImportCk -f "./model.yaml" -w

If the script targets multiple tenants, create one client_credentials client per tenant and switch contexts before each login. The same env-var names work across contexts; the active context determines which tenant the credentials authenticate against.

Backup and Restore​

Backup​

octo-cli -c Dump -tid "production" -f "./backup.tar.gz"

Restore to a New Tenant​

  1. Create the target tenant:

    octo-cli -c Create -tid "staging" -db "staging_db"

  2. Grant yourself access:

    octo-cli -c ProvisionCurrentUser -ttid "staging"

  3. Restore from backup:

    octo-cli -c Restore `
      -tid "staging" `
      -db "staging_db" `
      -f "./backup-20241213.tar.gz" `
      -w

  4. Clear tenant cache:

    octo-cli -c ClearCache -tid "staging"

  5. Re-provision yourself (cache reset may have invalidated previous grant):

    octo-cli -c ProvisionCurrentUser -ttid "staging"

See Tenant Lifecycle for detailed backup and restore guidance.

Deploy and Execute a Pipeline​

  1. Enable communication for the tenant:

    octo-cli -c EnableCommunication

  2. Verify the adapter is connected:

    octo-cli -c GetAdapters

  3. Deploy a pipeline definition — the central Communication Operator picks this up and rolls out the adapter via Helm automatically:

    octo-cli -c DeployPipeline `
      -aid "<adapter-rtId>" `
      -pid "<pipeline-rtId>" `
      -f "./my-pipeline.yaml"

  4. Execute the pipeline:

    octo-cli -c ExecutePipeline -id "<pipeline-rtId>"

  5. Check execution result:

    octo-cli -c GetLatestPipelineExecution -id "<pipeline-rtId>"

  6. Inspect debug points (if debugging is enabled):

    octo-cli -c GetPipelineDebugPoints -id "<pipeline-rtId>" -eid "<execution-guid>"

See DataFlows & Pipelines for details on pipeline definitions.

Add Local-Dev Callbacks to a Blueprint-Managed Client​

Blueprint-managed clients (octo-data-refinery-studio, octo-cli, the swagger UIs) carry the URIs the blueprint shipped — typically pointed at the deployed environment. To add local-dev URIs (http://localhost:4200/auth-callback, …) without losing them on the next blueprint apply, use the overlay endpoint. The entries are tagged Source = "overlay:<name>" and survive every re-apply.

  1. Login to the local environment (sets the active context):

    Invoke-OctoCliLoginLocal -tenantId "meshtest"

  2. Apply the canonical local-dev overlay (PowerShell cmdlet fans the per-client invocation):

    Apply-IdentityOverlay

    For one client only, call octo-cli directly:

    octo-cli -c ApplyClientOverlay `
      -id "octo-data-refinery-studio" `
      -n  "local-dev" `
      -r  "http://localhost:4200/auth-callback,http://localhost:4200/silent-renew" `
      -plr "http://localhost:4200/" `
      -co "http://localhost:4200"

  3. Verify — the next invocation is a no-op (every URI hits the dedup branch):

    Apply-IdentityOverlay -DryRun  # prints the invocations
    Apply-IdentityOverlay          # re-runs idempotently, all SkippedDuplicate

  4. Clean export — when dumping the tenant to share with another developer or commit as seed material, strip the overlay entries first so they don't leak. Three separate commands (the dump is a raw mongodump archive; the filter has to happen before the dump rather than inside it):

    octo-cli -c CleanClientOverlays -y                                    # strip every overlay:* entry
    octo-cli -c DumpTenant -tid "meshtest" -f ./meshtest-clean.tar.gz      # dump the now-clean tenant
    Apply-IdentityOverlay                                                  # optional: restore local-dev overlays (idempotent)

    To strip only a specific overlay name (e.g. drop personal overlays while keeping the shared local-dev set), pass -n <name>:

    octo-cli -c CleanClientOverlays -n gerald-laptop -y

See Clients and API Scopes → URI Sources and Lifecycle for the conceptual background (source taxonomy, family vs overlay, lifecycle across blueprint re-applies), and Apply-IdentityOverlay for the cmdlet's full parameter set.