octo-cli

octo-cli is the command-line interface for managing and administering OctoMesh. It provides commands for configuring services, managing tenants, users, identity providers, and more.

Installation

See Prerequisites for installation instructions.

Quick install:

# Windows (winget)
winget install -e --id meshmakers.octo-cli

# Windows (chocolatey)
choco install octo-cli

Alternatively, download from the Download Center.

Usage

octo-cli -c <Command> [arguments]

Arguments can be specified with short (-x) or long (--argument) form. Argument names are case-insensitive.

Configuration

Before using octo-cli, configure the service endpoints:

octo-cli -c Config \
  -isu "https://localhost:5003/" \
  -asu "https://localhost:5001/" \
  -bsu "https://localhost:5009/" \
  -csu "https://localhost:5015/" \
  -tid "meshtest"

Short	Long	Description
-isu	--identityServicesUri	URI of Identity Services (required)
-asu	--assetServicesUri	URI of Asset Repository Services
-bsu	--bobServicesUri	URI of Bot Services
-csu	--communicationServicesUri	URI of Communication Services
-rsu	--reportingServicesUri	URI of Reporting Services
-apu	--adminPanelUri	URI of Admin Panel
-tid	--tenantId	Default tenant ID

Authentication

Interactive Login

octo-cli -c LogIn -i

Opens a browser for device authentication.

Short	Long	Description
-i	--interactive	Use interactive browser-based authentication

Check Authentication Status

octo-cli -c AuthStatus

No parameters required.

---

General Commands

Command	Description
Config	Configure service endpoints
LogIn	Authenticate with Identity Services
AuthStatus	Check authentication status
Setup	Initial setup of Identity Services

Setup

Initial setup for Identity Services with admin credentials:

octo-cli -c Setup -e "admin@example.com" -p "SecurePassword123"

Short	Long	Description
-e	--email	Admin email address (required)
-p	--password	Admin password (required)

---

Identity Services

Clients

Clients are applications that can authenticate with OctoMesh.

List Clients

octo-cli -c GetClients

No parameters required.

Add Authorization Code Client

For web applications with user login:

octo-cli -c AddAuthorizationCodeClient \
  -id "my-web-app" \
  -n "My Web Application" \
  -u "https://myapp.example.com/" \
  -ru "https://myapp.example.com/callback"

Short	Long	Description
-id	--clientId	Unique client identifier (required)
-n	--name	Display name (required)
-u	--clientUri	Client URI (required)
-ru	--redirectUri	Redirect URI for login callback

Add Client Credentials Client

For service-to-service authentication:

octo-cli -c AddClientCredentialsClient \
  -id "my-service" \
  -n "My Background Service" \
  -s "MySecretKey123"

Short	Long	Description
-id	--clientId	Unique client identifier (required)
-n	--name	Display name (required)
-s	--secret	Client secret (required)

Add Device Code Client

For devices without browser support:

octo-cli -c AddDeviceCodeClient \
  -id "my-device" \
  -n "My IoT Device" \
  -s "DeviceSecret123"

Short	Long	Description
-id	--clientId	Unique client identifier (required)
-n	--name	Display name (required)
-s	--secret	Client secret (required)

Update Client

octo-cli -c UpdateClient -id "my-web-app" -n "Updated App Name"

Short	Long	Description
-id	--clientId	Client identifier (required)
-n	--name	New display name
-u	--clientUri	New client URI
-ru	--redirectUri	New redirect URI

Delete Client

octo-cli -c DeleteClient -id "my-web-app"

Short	Long	Description
-id	--clientId	Client identifier to delete (required)

Add Scope to Client

Grant API access to a client:

octo-cli -c AddScopeToClient -id "my-web-app" -n "assetSystemAPI.full_access"

Short	Long	Description
-id	--clientId	Client identifier (required)
-n	--name	Scope name to add (required)

Client Secrets

Create Client Secret

octo-cli -c CreateApiSecretClient \
  -cid "my-client" \
  -e "2025-12-31" \
  -d "Production secret"

Short	Long	Description
-cid	--clientId	Client identifier (required)
-e	--expiration	Expiration date (YYYY-MM-DD)
-d	--description	Secret description

List Client Secrets

octo-cli -c GetApiSecretsClient -cid "my-client"

Short	Long	Description
-cid	--clientId	Client identifier (required)

Update Client Secret

octo-cli -c UpdateApiSecretClient \
  -cid "my-client" \
  -s "sha256-encoded-value" \
  -e "2026-12-31"

Short	Long	Description
-cid	--clientId	Client identifier (required)
-s	--secret	SHA256-encoded secret value (required)
-e	--expiration	New expiration date (YYYY-MM-DD)
-d	--description	New description

Delete Client Secret

octo-cli -c DeleteApiSecretClient -cid "my-client" -s "sha256-encoded-value"

Short	Long	Description
-cid	--clientId	Client identifier (required)
-s	--secret	SHA256-encoded secret value (required)

Identity Providers

List Identity Providers

octo-cli -c GetIdentityProviders

No parameters required.

Add Azure Entra ID Provider

octo-cli -c AddAzureEntryIdIdentityProvider \
  -n "Azure AD" \
  -t "your-tenant-id" \
  -cid "your-client-id" \
  -cs "your-client-secret" \
  -e true \
  -asr true \
  -dgid "<default-group-rtid>"

Short	Long	Description
-n	--name	Provider display name (required)
-t	--tenantId	Azure tenant ID (required)
-cid	--clientId	Azure application client ID (required)
-cs	--clientSecret	Azure application client secret (required)
-e	--enabled	Enable provider (true/false)
-asr	--allowSelfRegistration	Allow new users to register on first login (true/false)
-dgid	--defaultGroupRtId	RtId of a group to assign to new users

Add OAuth Provider

Supports Google, Microsoft, Facebook:

octo-cli -c AddOAuthIdentityProvider \
  -n "Google Login" \
  -t "google" \
  -cid "your-client-id" \
  -cs "your-client-secret" \
  -e true \
  -asr true \
  -dgid "<default-group-rtid>"

Short	Long	Description
-n	--name	Provider display name (required)
-t	--type	Provider type: google, microsoft, facebook (required)
-cid	--clientId	OAuth client ID (required)
-cs	--clientSecret	OAuth client secret (required)
-e	--enabled	Enable provider (true/false)
-asr	--allowSelfRegistration	Allow new users to register on first login (true/false)
-dgid	--defaultGroupRtId	RtId of a group to assign to new users

Add Active Directory Provider

octo-cli -c AddAdIdentityProvider \
  -n "Corporate AD" \
  -h "ldap.example.com" \
  -p 389 \
  -e true \
  -asr false

Short	Long	Description
-n	--name	Provider display name (required)
-h	--host	LDAP server hostname (required)
-p	--port	LDAP server port (required)
-e	--enabled	Enable provider (true/false)
-asr	--allowSelfRegistration	Allow new users to register on first login (true/false)
-dgid	--defaultGroupRtId	RtId of a group to assign to new users

Add OpenLDAP Provider

octo-cli -c AddOpenLdapIdentityProvider \
  -n "OpenLDAP" \
  -h "ldap.example.com" \
  -p 389 \
  -ubdn "cn=users,dc=example,dc=com" \
  -uan "uid" \
  -e true \
  -asr false

Short	Long	Description
-n	--name	Provider display name (required)
-h	--host	LDAP server hostname (required)
-p	--port	LDAP server port (required)
-ubdn	--userBaseDn	Base DN for user searches (required)
-uan	--userAttributeName	Attribute name for user identifier (required)
-e	--enabled	Enable provider (true/false)
-asr	--allowSelfRegistration	Allow new users to register on first login (true/false)
-dgid	--defaultGroupRtId	RtId of a group to assign to new users

Add OctoTenant Provider

Delegates authentication to a parent tenant for cross-tenant access. See Cross-Tenant Authentication for details.

octo-cli -c AddOctoTenantIdentityProvider \
  -n "Parent Tenant Auth" \
  -ptid "octosystem" \
  -e true \
  -asr true \
  -dgid "<default-group-rtid>"

Short	Long	Description
-n	--name	Provider display name (required)
-ptid	--parentTenantId	Parent tenant ID to authenticate against (required)
-e	--enabled	Enable provider (true/false, required)
-asr	--allowSelfRegistration	Allow new users to register on first login (true/false)
-dgid	--defaultGroupRtId	RtId of a group to assign to new users

Update Identity Provider

Works for all provider types. Fetches the existing provider, preserves type-specific properties, and applies the changes:

octo-cli -c UpdateIdentityProvider \
  -id "provider-id" \
  -n "Updated Name" \
  -e true \
  -asr false \
  -dgid "<default-group-rtid>"

For OAuth-based providers, you can also update client credentials:

octo-cli -c UpdateIdentityProvider \
  -id "provider-id" \
  -n "Updated Name" \
  -e true \
  -cid "new-client-id" \
  -cs "new-client-secret"

Short	Long	Description
-id	--id	Provider ID (required)
-n	--name	New display name
-e	--enabled	Enable/disable provider (true/false)
-cid	--clientId	New client ID (OAuth providers only)
-cs	--clientSecret	New client secret (OAuth providers only)
-asr	--allowSelfRegistration	Allow new users to register on first login (true/false)
-dgid	--defaultGroupRtId	RtId of a group to assign to new users

Delete Identity Provider

octo-cli -c DeleteIdentityProvider -id "provider-id"

Short	Long	Description
-id	--id	Provider ID to delete (required)

API Resources & Scopes

List API Resources

octo-cli -c GetApiResources

No parameters required.

Create API Resource

octo-cli -c CreateApiResource \
  -n "myAPI" \
  -dn "My Custom API" \
  -d "API for custom functionality" \
  -s "myAPI.read,myAPI.write"

Short	Long	Description
-n	--name	API resource name (required)
-dn	--displayName	Display name
-d	--description	API description
-s	--scopes	Comma-separated list of scopes

Update API Resource

octo-cli -c UpdateApiResource -n "myAPI" -dn "Updated API Name"

Short	Long	Description
-n	--name	API resource name (required)
-dn	--displayName	New display name
-d	--description	New description

Delete API Resource

octo-cli -c DeleteApiResource -n "myAPI"

Short	Long	Description
-n	--name	API resource name to delete (required)

List API Scopes

octo-cli -c GetApiScopes

No parameters required.

Create API Scope

octo-cli -c CreateApiScope \
  -n "myAPI.admin" \
  -dn "Admin Access" \
  -d "Full administrative access" \
  -e true

Short	Long	Description
-n	--name	Scope name (required)
-dn	--displayName	Display name
-d	--description	Scope description
-e	--enabled	Enable scope (true/false)

Update API Scope

octo-cli -c UpdateApiScope -n "myAPI.admin" -nn "myAPI.superadmin"

Short	Long	Description
-n	--name	Current scope name (required)
-nn	--newName	New scope name
-dn	--displayName	New display name
-d	--description	New description

Delete API Scope

octo-cli -c DeleteApiScope -n "myAPI.admin"

Short	Long	Description
-n	--name	Scope name to delete (required)

API Resource Secrets

Create API Resource Secret

octo-cli -c CreateApiSecretApiResource -n "myAPI" -e "2025-12-31" -d "API secret"

Short	Long	Description
-n	--name	API resource name (required)
-e	--expiration	Expiration date (YYYY-MM-DD)
-d	--description	Secret description

List API Resource Secrets

octo-cli -c GetApiSecretsApiResource -n "myAPI"

Short	Long	Description
-n	--name	API resource name (required)

Update API Resource Secret

octo-cli -c UpdateApiSecretApiResource -n "myAPI" -s "sha256-value" -e "2026-12-31"

Short	Long	Description
-n	--name	API resource name (required)
-s	--secret	SHA256-encoded secret value (required)
-e	--expiration	New expiration date (YYYY-MM-DD)
-d	--description	New description

Delete API Resource Secret

octo-cli -c DeleteApiSecretApiResource -n "myAPI" -s "sha256-value"

Short	Long	Description
-n	--name	API resource name (required)
-s	--secret	SHA256-encoded secret value (required)

Users

List Users

octo-cli -c GetUsers

No parameters required.

Create User

octo-cli -c CreateUser \
  -un "john.doe" \
  -e "john.doe@example.com" \
  -p "SecurePassword123"

Short	Long	Description
-un	--userName	Username (required)
-e	--email	Email address (required)
-p	--password	Password (required)

Update User

octo-cli -c UpdateUser -un "john.doe" -e "new.email@example.com"

Short	Long	Description
-un	--userName	Username (required)
-e	--email	New email address

Reset Password

octo-cli -c ResetPassword -un "john.doe" -p "NewPassword456"

Short	Long	Description
-un	--userName	Username (required)
-p	--password	New password (required)

Delete User

octo-cli -c DeleteUser -un "john.doe"

Short	Long	Description
-un	--userName	Username to delete (required)

Roles

List Roles

octo-cli -c GetRoles

No parameters required.

Create Role

octo-cli -c CreateRole -n "DataAnalyst"

Short	Long	Description
-n	--name	Role name (required)

Update Role

octo-cli -c UpdateRole -n "DataAnalyst" -nn "SeniorDataAnalyst"

Short	Long	Description
-n	--name	Current role name (required)
-nn	--newName	New role name (required)

Delete Role

octo-cli -c DeleteRole -n "DataAnalyst"

Short	Long	Description
-n	--name	Role name to delete (required)

Add User to Role

octo-cli -c AddUserToRole -un "john.doe" -r "DataAnalyst"

Short	Long	Description
-un	--userName	Username (required)
-r	--role	Role name (required)

Remove User from Role

octo-cli -c RemoveUserFromRole -un "john.doe" -r "DataAnalyst"

Short	Long	Description
-un	--userName	Username (required)
-r	--role	Role name (required)

Groups

Groups simplify role management by assigning roles to a group and then adding users to that group. See Groups for details.

List Groups

octo-cli -c GetGroups

No parameters required.

Get Group

octo-cli -c GetGroup -id "<group-rtid>"

Short	Long	Description
-id	--id	Group RtId (required)

Create Group

octo-cli -c CreateGroup -n "Engineering" -d "Engineering team" -rids "Development,CommunicationManagement"

Short	Long	Description
-n	--name	Group name (required)
-d	--description	Group description
-rids	--roleIds	Comma-separated role IDs to assign

Update Group

octo-cli -c UpdateGroup -id "<group-rtid>" -n "New Name" -d "New description"

Short	Long	Description
-id	--id	Group RtId (required)
-n	--name	New group name (required)
-d	--description	New description

Delete Group

octo-cli -c DeleteGroup -id "<group-rtid>"

Short	Long	Description
-id	--id	Group RtId to delete (required)

Update Group Roles

Replace all roles assigned to a group:

octo-cli -c UpdateGroupRoles -id "<group-rtid>" -rids "Development,DashboardViewer,ReportingViewer"

Short	Long	Description
-id	--id	Group RtId (required)
-rids	--roleIds	Comma-separated role IDs (required)

Add User to Group

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

Short	Long	Description
-id	--id	Group RtId (required)
-uid	--userId	User ID to add (required)

Remove User from Group

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

Short	Long	Description
-id	--id	Group RtId (required)
-uid	--userId	User ID to remove (required)

Add Child Group

octo-cli -c AddGroupToGroup -id "<parent-group-rtid>" -cgid "<child-group-rtid>"

Short	Long	Description
-id	--id	Parent group RtId (required)
-cgid	--childGroupId	Child group RtId to add (required)

Remove Child Group

octo-cli -c RemoveGroupFromGroup -id "<parent-group-rtid>" -cgid "<child-group-rtid>"

Short	Long	Description
-id	--id	Parent group RtId (required)
-cgid	--childGroupId	Child group RtId to remove (required)

Email Domain Group Rules

Automatically assign users to groups based on their email address domain. See Email Domain Group Rules for details.

List Email Domain Group Rules

octo-cli -c GetEmailDomainGroupRules

No parameters required.

Get Email Domain Group Rule

octo-cli -c GetEmailDomainGroupRule -id "<rule-rtid>"

Short	Long	Description
-id	--id	Rule RtId (required)

Create Email Domain Group Rule

octo-cli -c CreateEmailDomainGroupRule \
  -edp "meshmakers.com" \
  -tgid "<target-group-rtid>" \
  -d "Auto-assign meshmakers employees"

Short	Long	Description
-edp	--emailDomainPattern	Email domain to match (required)
-tgid	--targetGroupRtId	Target group RtId (required)
-d	--description	Rule description

Update Email Domain Group Rule

octo-cli -c UpdateEmailDomainGroupRule \
  -id "<rule-rtid>" \
  -edp "meshmakers.com" \
  -tgid "<new-target-group-rtid>"

Short	Long	Description
-id	--id	Rule RtId (required)
-edp	--emailDomainPattern	Email domain to match (required)
-tgid	--targetGroupRtId	Target group RtId (required)
-d	--description	Rule description

Delete Email Domain Group Rule

octo-cli -c DeleteEmailDomainGroupRule -id "<rule-rtid>"

Short	Long	Description
-id	--id	Rule RtId to delete (required)

External Tenant User Mappings

Manage cross-tenant user mappings that link users from a parent tenant to roles in the current tenant. See Cross-Tenant Authentication for details.

List External Tenant User Mappings

octo-cli -c GetExternalTenantUserMappings -stid "octosystem"

Short	Long	Description
-skip	--skip	Number of items to skip (pagination)
-take	--take	Number of items to return (pagination)
-stid	--sourceTenantId	Filter by source tenant ID

Get External Tenant User Mapping

octo-cli -c GetExternalTenantUserMapping -id "<mapping-rtid>"

Short	Long	Description
-id	--id	Mapping RtId (required)

Create External Tenant User Mapping

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

Short	Long	Description
-stid	--sourceTenantId	Source (parent) tenant ID (required)
-suid	--sourceUserId	User ID in the parent tenant (required)
-sun	--sourceUserName	Username in the parent tenant (required)
-rids	--roleIds	Comma-separated role IDs to assign

Update External Tenant User Mapping

octo-cli -c UpdateExternalTenantUserMapping \
  -id "<mapping-rtid>" \
  -rids "Development,TenantManagement"

Short	Long	Description
-id	--id	Mapping RtId (required)
-rids	--roleIds	Comma-separated role IDs to assign

Delete External Tenant User Mapping

octo-cli -c DeleteExternalTenantUserMapping -id "<mapping-rtid>"

Short	Long	Description
-id	--id	Mapping RtId to delete (required)

Admin Provisioning

Admin provisioning allows system tenant administrators to pre-create user mappings in target tenants without needing prior access. See Cross-Tenant Authentication for details.

All admin provisioning commands must be run from the system tenant context.

List Admin Provisioning Mappings

octo-cli -c GetAdminProvisioningMappings -ttid "customer-project"

Short	Long	Description
-ttid	--targetTenantId	Target tenant ID (required)

Create Admin Provisioning Mapping

octo-cli -c CreateAdminProvisioningMapping \
  -ttid "customer-project" \
  -stid "octosystem" \
  -suid "<user-id>" \
  -sun "alice" \
  -rids "Development,DashboardViewer"

Short	Long	Description
-ttid	--targetTenantId	Target tenant ID (required)
-stid	--sourceTenantId	Source (parent) tenant ID (required)
-suid	--sourceUserId	User ID in the source tenant (required)
-sun	--sourceUserName	Username in the source tenant (required)
-rids	--roleIds	Comma-separated role IDs to assign

Provision Current User

Provision yourself in a target tenant with all available roles and TenantOwners group membership:

octo-cli -c ProvisionCurrentUser -ttid "customer-project"

Short	Long	Description
-ttid	--targetTenantId	Target tenant ID (required)

Delete Admin Provisioning Mapping

octo-cli -c DeleteAdminProvisioningMapping -ttid "customer-project" -mid "<mapping-rtid>"

Short	Long	Description
-ttid	--targetTenantId	Target tenant ID (required)
-mid	--mappingId	Mapping RtId to delete (required)

---

Asset Repository Services

Tenant Management

Create Tenant

octo-cli -c Create -tid "newtenant" -db "newtenant_db"

Short	Long	Description
-tid	--tenantId	Tenant identifier (required)
-db	--database	Database name (required)

Delete Tenant

octo-cli -c Delete -tid "newtenant"

Short	Long	Description
-tid	--tenantId	Tenant identifier to delete (required)

Attach Database to Tenant

octo-cli -c Attach -tid "newtenant" -db "existing_db"

Short	Long	Description
-tid	--tenantId	Tenant identifier (required)
-db	--database	Database name to attach (required)

Clean Tenant

Reset tenant to factory defaults:

octo-cli -c Clean -tid "newtenant"

Short	Long	Description
-tid	--tenantId	Tenant identifier to clean (required)

Clear Tenant Cache

octo-cli -c ClearCache -tid "newtenant"

Short	Long	Description
-tid	--tenantId	Tenant identifier (required)

Update System CK Model

Update system construction kit model to latest version:

octo-cli -c UpdateSystemCkModel -tid "newtenant"

Short	Long	Description
-tid	--tenantId	Tenant identifier (required)

Import & Export

Import Construction Kit

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

Short	Long	Description
-f	--file	Path to CK file (required)
-w	--wait	Wait for job completion

Import Runtime Model

octo-cli -c ImportRt -f "./runtime-data.json" -w -r

Short	Long	Description
-f	--file	Path to RT file (required)
-w	--wait	Wait for job completion
-r	--replace	Replace existing entities

Export Runtime Model by Query

octo-cli -c ExportRtByQuery -f "./export.zip" -q "query-id"

Short	Long	Description
-f	--file	Output file path (required)
-q	--queryId	Query ID to use for export (required)

Export Runtime Model by Deep Graph

octo-cli -c ExportRtByDeepGraph \
  -f "./export.zip" \
  -id "rtId1;rtId2;rtId3" \
  -t "MyNamespace/MyType-1"

Short	Long	Description
-f	--file	Output file path (required)
-id	--rtIds	Semicolon-separated list of runtime entity IDs (required)
-t	--ckTypeId	Construction Kit type ID filter

Stream Data

Enable Stream Data

octo-cli -c EnableStreamData

No parameters required.

Disable Stream Data

octo-cli -c DisableStreamData

No parameters required.

Fixup Scripts

Create Fixup Script

octo-cli -c CreateFixupScript \
  -n "Migration Script" \
  -f "./migration.js" \
  -o 10 \
  -e true

Short	Long	Description
-n	--name	Script name (required)
-f	--file	Script file path (required)
-o	--orderNumber	Execution order (required)
-e	--enabled	Enable script (true/false, required)
-r	--replace	Replace existing script with same name

Run Fixup Scripts

octo-cli -c RunFixupScripts -w

Short	Long	Description
-w	--wait	Wait for job completion

---

Bot Services

Backup & Restore

Dump Tenant

Create a backup of a tenant:

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

Short	Long	Description
-tid	--tenantId	Tenant identifier (required)
-f	--file	Output backup file path (required)

Restore Tenant

Restore a tenant from backup:

octo-cli -c Restore \
  -tid "mytenant" \
  -db "mytenant_db" \
  -f "./backup.tar.gz" \
  -w

Short	Long	Description
-tid	--tenantId	Target tenant ID (required)
-db	--database	Database name (required)
-f	--file	Backup file path (required)
-oldDb	--oldDatabaseName	Original database name (if different)
-w	--wait	Wait for completion

Service Hooks

Service hooks allow triggering external services based on entity changes.

List Service Hooks

octo-cli -c GetServiceHooks

No parameters required.

Create Service Hook

octo-cli -c CreateServiceHook \
  -n "Status Change Hook" \
  -ck "MyNamespace/MyType-1" \
  -f "'State' Equals '2'" \
  -u "https://api.example.com" \
  -a "/webhook/status-change" \
  -k "my-api-key" \
  -e true

Short	Long	Description
-n	--name	Hook name (required)
-ck	--ckId	Construction Kit type ID (required)
-f	--filter	Filter expression (required)
-u	--uri	Base URI for webhook
-a	--action	Action path appended to URI
-k	--apiKey	API key for authentication
-e	--enabled	Enable hook (true/false, required)

Filter Operators:

• Equals, NotEquals
• LessThan, LessEqualThan, GreaterThan, GreaterEqualThan
• In, NotIn
• Like, MatchRegEx
• AnyEq, AnyLike

Update Service Hook

octo-cli -c UpdateServiceHook -id "hook-id" -e false

Short	Long	Description
-id	--id	Hook ID (required)
-n	--name	New hook name
-f	--filter	New filter expression
-u	--uri	New base URI
-a	--action	New action path
-k	--apiKey	New API key
-e	--enabled	Enable/disable hook (true/false)

Delete Service Hook

octo-cli -c DeleteServiceHook -id "hook-id"

Short	Long	Description
-id	--id	Hook ID to delete (required)

---

Communication Services

Enable Communication

octo-cli -c EnableCommunication

No parameters required.

Disable Communication

octo-cli -c DisableCommunication

No parameters required.

Adapters

Adapters are external clients that connect to OctoMesh and execute data pipelines. See Adapters for details.

All adapter commands accept plain runtime object IDs. The CLI handles the internal ID formatting automatically.

List Adapters

octo-cli -c GetAdapters

Short	Long	Description
-j	--json	Output as compact JSON

Get Adapter Configuration

octo-cli -c GetAdapter -id "69cfa838092b710403248acd"

Short	Long	Description
-id	--identifier	Adapter runtime ID (required)
-j	--json	Output as compact JSON

Get Adapter Nodes

Returns the list of available pipeline node types from all connected adapters:

octo-cli -c GetAdapterNodes

Short	Long	Description
-j	--json	Output as compact JSON

Get Pipeline Schema

Returns the JSON Schema describing valid pipeline definitions for a specific adapter:

octo-cli -c GetPipelineSchema -aid "69cfa838092b710403248acd"

Short	Long	Description
-aid	--adapterId	Adapter runtime ID (required)
-o	--outputFile	Write schema to file instead of stdout

Deploy Adapter

Pushes the current pipeline configuration to the adapter:

octo-cli -c DeployAdapter -id "69cfa838092b710403248acd"

Short	Long	Description
-id	--identifier	Adapter runtime ID (required)

Pipelines

Pipelines define data processing workflows. They are associated with an adapter and a data flow.

Get Pipeline Status

octo-cli -c GetPipelineStatus -id "cc0000000000000000000003"

Short	Long	Description
-id	--identifier	Pipeline runtime ID (required)
-j	--json	Output as compact JSON

Deploy Pipeline

Deploys a pipeline definition from a YAML or JSON file:

octo-cli -c DeployPipeline \
  -aid "69cfa838092b710403248acd" \
  -pid "cc0000000000000000000003" \
  -f "./my-pipeline.yaml"

Short	Long	Description
-aid	--adapterId	Adapter runtime ID (required)
-pid	--pipelineId	Pipeline runtime ID (required)
-f	--file	Path to pipeline definition file (required)

Execute Pipeline

Triggers a pipeline execution and returns the execution ID:

octo-cli -c ExecutePipeline -id "cc0000000000000000000003"

Optionally provide input data from a file:

octo-cli -c ExecutePipeline -id "cc0000000000000000000003" -f "./input.json"

Short	Long	Description
-id	--identifier	Pipeline runtime ID (required)
-f	--inputFile	Path to pipeline input file (JSON)

List Pipeline Executions

octo-cli -c GetPipelineExecutions -id "cc0000000000000000000003"

Short	Long	Description
-id	--identifier	Pipeline runtime ID (required)
-j	--json	Output as compact JSON

Get Latest Pipeline Execution

octo-cli -c GetLatestPipelineExecution -id "cc0000000000000000000003"

Short	Long	Description
-id	--identifier	Pipeline runtime ID (required)
-j	--json	Output as compact JSON

Get Pipeline Debug Points

Returns the debug point node tree for a specific pipeline execution:

octo-cli -c GetPipelineDebugPoints \
  -id "cc0000000000000000000003" \
  -eid "7c011b03-b738-4be7-948c-78ee28e4b233"

Short	Long	Description
-id	--identifier	Pipeline runtime ID (required)
-eid	--executionId	Execution ID as GUID (required)
-j	--json	Output as compact JSON

Pipeline Triggers

Pipeline triggers schedule automatic pipeline executions based on cron expressions. See Pipeline Triggers for details.

Deploy Triggers

Activates all pipeline triggers for the current tenant:

octo-cli -c DeployTriggers

No parameters required.

Undeploy Triggers

Deactivates all pipeline triggers for the current tenant:

octo-cli -c UndeployTriggers

No parameters required.

Pools

Pools group managed devices and their adapters. See Pools for details.

List Pools

octo-cli -c GetPools

Short	Long	Description
-j	--json	Output as compact JSON

Get Pool Configuration

octo-cli -c GetPool -id "cc0000000000000000000001"

Short	Long	Description
-id	--identifier	Pool runtime ID (required)
-j	--json	Output as compact JSON

Deploy Pool Adapters

Deploy all adapters in a pool, or a specific adapter:

# Deploy all adapters in pool
octo-cli -c DeployPoolAdapters -pid "cc0000000000000000000001"

# Deploy a specific adapter in pool
octo-cli -c DeployPoolAdapters -pid "cc0000000000000000000001" -aid "69cfa838092b710403248acd"

Short	Long	Description
-pid	--poolId	Pool runtime ID (required)
-aid	--adapterId	Deploy only this adapter (optional)

Undeploy Pool Adapters

Undeploy all adapters from a pool, or a specific adapter:

# Undeploy all adapters from pool
octo-cli -c UndeployPoolAdapters -pid "cc0000000000000000000001"

# Undeploy a specific adapter from pool
octo-cli -c UndeployPoolAdapters -pid "cc0000000000000000000001" -aid "69cfa838092b710403248acd"

Short	Long	Description
-pid	--poolId	Pool runtime ID (required)
-aid	--adapterId	Undeploy only this adapter (optional)

Data Flows

Data flows group pipelines and their triggers into a deployable unit. See DataFlows & Pipelines for details.

Deploy Data Flow

octo-cli -c DeployDataFlow -id "cc0000000000000000000002"

Short	Long	Description
-id	--identifier	Data flow runtime ID (required)

Undeploy Data Flow

octo-cli -c UndeployDataFlow -id "cc0000000000000000000002"

Short	Long	Description
-id	--identifier	Data flow runtime ID (required)

Get Data Flow Status

Returns the aggregated execution status of a data flow and its pipelines:

octo-cli -c GetDataFlowStatus -id "cc0000000000000000000002"

Short	Long	Description
-id	--identifier	Data flow runtime ID (required)
-j	--json	Output as compact JSON

---

Reporting Services

Enable Reporting

octo-cli -c EnableReporting

No parameters required.

Disable Reporting

octo-cli -c DisableReporting

No parameters required.

---

DevOps

Generate Operator Certificates

Generate certificates for OctoMesh Kubernetes operator:

octo-cli -c GenerateOperatorCertificates \
  -o "./certs" \
  -s "octo-mesh-op1-communication-operator" \
  -n "octo-operator-system"

Short	Long	Description
-o	--output	Output directory (required)
-s	--serverName	Service/server name (required)
-n	--namespace	Kubernetes namespace (required)

---

Diagnostics

Reconfigure Log Level

Adjust logging levels for troubleshooting:

octo-cli -c ReconfigureLogLevel \
  -n "AssetRepository" \
  -ln "Meshmakers.*" \
  -minL "Debug" \
  -maxL "Error"

Short	Long	Description
-n	--serviceName	Service name: Identity, AssetRepository, Bot, CommunicationController, AdminPanel, Reporting (required)
-ln	--loggerName	Logger pattern: Microsoft.*, Meshmakers.*, Masstransit.*, * (required)
-minL	--minLogLevel	Minimum level: Trace, Debug, Info, Warn, Error, Fatal, Off (required)
-maxL	--maxLogLevel	Maximum level: Trace, Debug, Info, Warn, Error, Fatal, Off (required)

---

Common Workflows

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"
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.

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

# 1. In child tenant: add OctoTenant provider pointing to parent
octo-cli -c Config -tid "child-tenant"
octo-cli -c LogIn -i
octo-cli -c AddOctoTenantIdentityProvider -n "Parent Auth" -ptid "octosystem" -e true

# 2. Create user mappings
octo-cli -c CreateExternalTenantUserMapping \
  -stid "octosystem" -suid "<user-id>" -sun "alice" \
  -rids "Development,DashboardViewer"

See Cross-Tenant Authentication for details.

Backup and Restore

# Backup
octo-cli -c Dump -tid "production" -f "./backup-$(date +%Y%m%d).tar.gz"

# Restore to new tenant
octo-cli -c Create -tid "staging" -db "staging_db"
octo-cli -c ProvisionCurrentUser -ttid "staging"
octo-cli -c Restore -tid "staging" -db "staging_db" -f "./backup-20241213.tar.gz" -w
octo-cli -c ClearCache -tid "staging"
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
octo-cli -c DeployPipeline \
  -aid "<adapter-rtId>" \
  -pid "<pipeline-rtId>" \
  -f "./my-pipeline.yaml"

# 4. Deploy the adapter to push configuration
octo-cli -c DeployAdapter -id "<adapter-rtId>"

# 5. Execute the pipeline
octo-cli -c ExecutePipeline -id "<pipeline-rtId>"

# 6. Check execution result
octo-cli -c GetLatestPipelineExecution -id "<pipeline-rtId>"

# 7. 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.

CK Model Library Management

Commands for browsing, importing, and managing Construction Kit model libraries from catalogs. See Library Management for the underlying concepts.

ListCatalogs

Lists available CK model catalog sources.

octo-cli -c ListCatalogs

Output:

NAME                           DESCRIPTION
------------------------------ ----------------------------------------
EmbeddedResourceCatalog        Embedded resource catalog
LocalFileSystemCatalog         Local file system catalog at '~/.octo/local-catalog'
PrivateGitHubCatalog           Private GitHub catalog for development and testing
PublicGitHubCatalog            Public GitHub catalog

ListCatalogModels

Lists CK models available in catalogs. Optionally filter by catalog name or search term.

Argument	Short	Description	Required
--catalogName	-cn	Filter by catalog name	No
--search	-q	Search term	No

# List all models
octo-cli -c ListCatalogModels

# Search for energy models
octo-cli -c ListCatalogModels -q "Energy"

# List from specific catalog
octo-cli -c ListCatalogModels -cn PublicGitHubCatalog

LibraryStatus

Shows the merged status of installed CK models and catalog availability for the configured tenant. Indicates which models need action (update, fix, install).

Argument	Short	Description	Required
--needs-action	-na	Show only models needing action	No
--installed-only	-io	Show only installed models	No

# Full status
octo-cli -c LibraryStatus

# Only models needing attention
octo-cli -c LibraryStatus -na

Output:

NAME                      INSTALLED    CATALOG      STATE           ACTION
------------------------- ------------ ------------ --------------- --------------------
System                    2.0.7        2.0.7        Available       Service-Managed
Basic                     2.0.2        2.0.2        Available       -
Industry.Energy           -            2.0.0        Not Installed   Install

CheckDependencies

Shows the full dependency tree for a CK model from a catalog, indicating what needs to be installed or updated.

Argument	Short	Description	Required
--catalogName	-cn	Catalog name	Yes
--modelId	-m	Model ID (e.g., Industry.Energy-2.0.0)	Yes

octo-cli -c CheckDependencies -cn PublicGitHubCatalog -m "Industry.Energy-2.0.0"

Output:

Industry.Energy v2.0.0  [INSTALL]
  Industry.Basic v2.1.0  [INSTALL]
    Basic v2.0.2  [NONE] (installed: v2.0.2)
    System v2.0.7  [NONE] (service-managed: v2.0.7)

Models to import (2):
  Industry.Basic-2.1.0
  Industry.Energy-2.0.0

CheckUpgrade

Pre-flight check showing whether importing a model will trigger migrations and whether breaking changes are involved.

Argument	Short	Description	Required
--catalogName	-cn	Catalog name	Yes
--modelId	-m	Model ID	Yes

octo-cli -c CheckUpgrade -cn PublicGitHubCatalog -m "Basic-2.0.2"

Output:

Model:              Basic
Installed Version:  2.0.0
Target Version:     2.0.2
Upgrade Needed:     True
Migration Path:     True
Breaking Changes:   False

ImportFromCatalog

Imports a CK model from a catalog including all required dependencies. Dependencies are resolved automatically and imported in the correct order.

Argument	Short	Description	Required
--catalogName	-cn	Catalog name	Yes
--modelId	-m	Model ID	Yes
--wait	-w	Wait for each import job to complete	No

# Import with wait
octo-cli -c ImportFromCatalog -cn PublicGitHubCatalog -m "Industry.Energy-2.0.0" -w

# Import without waiting (returns job IDs)
octo-cli -c ImportFromCatalog -cn PublicGitHubCatalog -m "Industry.Energy-2.0.0"

FixAll

Imports all CK models that need updating or fixing. Resolves dependencies across all affected models, deduplicates, and imports in the correct order.

Argument	Short	Description	Required
--wait	-w	Wait for each import job to complete	No
--yes	-y	Skip confirmation prompt	No

# Interactive with wait
octo-cli -c FixAll -w

# Non-interactive (for CI/CD)
octo-cli -c FixAll -w -y

RefreshCatalogs

Refreshes the CK model catalog caches. Useful after publishing new models to a catalog.

Argument	Short	Description	Required
--catalogName	-cn	Specific catalog to refresh (all if omitted)	No

# Refresh all catalogs
octo-cli -c RefreshCatalogs

# Refresh specific catalog
octo-cli -c RefreshCatalogs -cn PublicGitHubCatalog