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

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

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)

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

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)

Add Active Directory Provider

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

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)

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

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)

Update Identity Provider

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
`-cs`	`--clientSecret`	New client secret

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)

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.

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. Import construction kit
octo-cli -c ImportCk -f "./my-model.yaml" -w

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"

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 Restore -tid "staging" -db "staging_db" -f "./backup-20241213.tar.gz" -w

Installation​

Usage​

Configuration​

Authentication​

Interactive Login​

Check Authentication Status​

General Commands​

Setup​

Identity Services​

Clients​

List Clients​

Add Authorization Code Client​

Add Client Credentials Client​

Add Device Code Client​

Update Client​

Delete Client​

Add Scope to Client​

Client Secrets​

Create Client Secret​

List Client Secrets​

Update Client Secret​

Delete Client Secret​

Identity Providers​

List Identity Providers​

Add Azure Entra ID Provider​

Add OAuth Provider​

Add Active Directory Provider​

Add OpenLDAP Provider​

Update Identity Provider​

Delete Identity Provider​

API Resources & Scopes​

List API Resources​

Create API Resource​

Update API Resource​

Delete API Resource​

List API Scopes​

Create API Scope​

Update API Scope​

Delete API Scope​

API Resource Secrets​

Create API Resource Secret​

List API Resource Secrets​

Update API Resource Secret​

Delete API Resource Secret​

Users​

List Users​

Create User​

Update User​

Reset Password​

Delete User​

Roles​

List Roles​

Create Role​

Update Role​

Delete Role​

Add User to Role​

Remove User from Role​

Asset Repository Services​

Tenant Management​

Create Tenant​

Delete Tenant​

Attach Database to Tenant​

Clean Tenant​

Clear Tenant Cache​

Update System CK Model​

Import & Export​

Import Construction Kit​

Import Runtime Model​

Export Runtime Model by Query​

Export Runtime Model by Deep Graph​

Stream Data​

Enable Stream Data​

Disable Stream Data​

Fixup Scripts​

Create Fixup Script​

Run Fixup Scripts​

Bot Services​

Backup & Restore​

Dump Tenant​

Restore Tenant​

Installation

Usage

Configuration

Authentication

Interactive Login

Check Authentication Status

General Commands

Setup

Identity Services

Clients

List Clients

Add Authorization Code Client

Add Client Credentials Client

Add Device Code Client

Update Client

Delete Client

Add Scope to Client

Client Secrets

Create Client Secret

List Client Secrets

Update Client Secret

Delete Client Secret

Identity Providers

List Identity Providers

Add Azure Entra ID Provider

Add OAuth Provider

Add Active Directory Provider

Add OpenLDAP Provider

Update Identity Provider

Delete Identity Provider

API Resources & Scopes

List API Resources

Create API Resource

Update API Resource

Delete API Resource

List API Scopes

Create API Scope

Update API Scope

Delete API Scope

API Resource Secrets

Create API Resource Secret

List API Resource Secrets

Update API Resource Secret

Delete API Resource Secret

Users

List Users

Create User

Update User

Reset Password

Delete User

Roles

List Roles

Create Role

Update Role

Delete Role

Add User to Role

Remove User from Role

Asset Repository Services

Tenant Management

Create Tenant

Delete Tenant

Attach Database to Tenant

Clean Tenant

Clear Tenant Cache

Update System CK Model

Import & Export

Import Construction Kit

Import Runtime Model

Export Runtime Model by Query

Export Runtime Model by Deep Graph

Stream Data

Enable Stream Data

Disable Stream Data

Fixup Scripts

Create Fixup Script

Run Fixup Scripts

Bot Services

Backup & Restore

Dump Tenant

Restore Tenant