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.

Command	Description
AddContext	Add or update a named context
UseContext	Switch the active context
ListContexts	List all contexts, or show details of one
RemoveContext	Remove 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"

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.