Octo

OctoMesh CLI Natural Language Interface

Overview

Single entry point: /octo <natural language> Claude infers the correct octo-cli command from the user's intent, resolves context (environment, tenant, auth status), and executes it — with confirmation for mutating operations.

Routing — Check Before Proceeding

This skill is the hub for all OctoMesh tasks. Before doing any work, check if the user's request belongs to a specialized sibling skill. If it does, invoke that skill immediately via the Skill tool and pass along the user's request — do NOT attempt to handle it here.

Routing rule for Communication / Pipelines: If the user wants to write or understand pipeline YAML, route to pipeline-expert. If they want to deploy, run, inspect status, or debug executions, handle it here in octo. For end-to-end workflows ("set up a new data flow"), octo orchestrates and routes to pipeline-expert only for the YAML authoring step.

Only continue with this skill if the request is about: CLI commands (octo-cli), data model exploration (CK models/types/enums), runtime instance browsing, GraphQL introspection, environment/auth management, or communication operations (adapters, pipeline deployment/execution/status, data flows, triggers).

Context Discovery

Run these checks once per session and cache the results. If any check has already been performed in this conversation, skip it.

1. Active Context

Read ~/.octo-cli/contexts.json to extract:

• ActiveContext — name of the currently active context (e.g., local_meshtest, staging-1_meshtest)
• From the active context entry:
  • OctoToolOptions.TenantId — configured tenant ID
  • OctoToolOptions.IdentityServiceUrl, OctoToolOptions.AssetServiceUrl, OctoToolOptions.BotServiceUrl, OctoToolOptions.CommunicationServiceUrl, OctoToolOptions.ReportingServiceUrl, OctoToolOptions.AiServiceUrl, OctoToolOptions.AdminPanelUrl — service endpoints
  • Authentication.AccessToken — current auth token (if logged in)

Reading ActiveContext tells you the persisted default — but a command may run against a different context when --context <name> is passed or OCTO_CLI_CONTEXT is set (see Invocation Syntax). Check the env var and prefer --context when targeting a specific environment so you never depend on, or mutate, the global active context.

To list all available contexts: octo-cli -c ListContexts — the dedicated command. Shows each context's identity URL, tenant, and auth status (none/authenticated/expired). Add -n <name> for single-context detail or -j for JSON. (octo-cli -c UseContext with no -n still lists contexts as a legacy fallback.)

2. Authentication Check

Run octo-cli -c AuthStatus to determine:

• Whether authenticated (token valid)
• Current identity service URL (determines environment)
• JWT claims: subject, roles, issuer, audience, expiration

If not authenticated: inform the user and offer to run octo-cli -c LogIn -i (interactive browser device login). For headless/CI scenarios use octo-cli -c LogInClientCredentials instead (reads -id/-s or the OCTO_CLI_CLIENT_ID/OCTO_CLI_CLIENT_SECRET env vars; tenant comes from the active context). AuthStatus shows an "Auth Method" line and omits the User Info section for client-credentials tokens. Agent-driven tasks that need a throwaway tenant never require interactive login — see references/temp-tenants.md.

3. Environment Detection from URLs

Invocation Syntax

octo-cli -c <CommandValue> [flags] — flags use the short form with a - prefix (-un userName, -e email, -tid tenantId), or the long form (--userName). All flags have both long and short forms (e.g. --json (-j), --identifier (-id)); the tables below and references/command-reference.md give the exact names.

Targeting a context — --context <name> (prefer this over UseContext). octo-cli -c <Command> --context <name> runs that one command against the named context without changing the active context. Resolution order: --context > env var OCTO_CLI_CONTEXT > persisted active context. The token is read from — and for LogIn/LogInClientCredentials written back to — the selected context, and saves merge per-context, so parallel Claude sessions (or a _train/CI job) pinned to different contexts never clobber each other. This is the default for any agent-driven or scripted flow. UseContext mutates the single global active context in ~/.octo-cli/contexts.json — a second session then silently flips it out from under the first; reserve it for a human setting a persistent default. To pin a whole shell session (octo-cli and the Python explorer scripts, which honor the same variable) without touching the file: export OCTO_CLI_CONTEXT=<name>. Only the full term matches — --context/-context//context, no abbreviation.

Command Reference (Quick Lookup)

Command-name + one-line purpose + safety type only. For full flag detail, read references/command-reference.md (organized by the same command groups). For environment URLs read references/environments.md. Verify flags there before assembling any mutating command.

Context Management & Auth (no group)

Identity Services

Active Directory IdPs support AD-group→OctoMesh-group sync: on every login, users in an AD group are added to the OctoMesh group whose name matches the AD group CN (case-insensitive). The matching OctoMesh group must already exist and carry the desired role associations.

Asset Repository Services

CK Catalog / Library Management

Requires the DataModelManagement role for catalog import/refresh.

Blueprints

Blueprint history/preview/update used to live in octo-bpm; those commands were removed — use these octo-cli commands. octo-bpm (authoring CLI) has new, validate, pack, list, version, catalogs, get, publish, unpublish, config. unpublish removes a blueprint/version from a catalog (inverse of publish; dry-run unless -f; -r <version> for one version, omit -r for all).

Stream-Data Archives (Time Series)

Archive lifecycle mutations require the StreamDataAdminRole.

Bot Services

Communication Services

All communication commands accept plain runtime object IDs — the SDK builds the composite RtEntityId internally. GetAdapters/GetPools return human-readable enum names (e.g. Online, Offline), not integers.

Adapters are now Helm-deployed by the Communication Operator when a pool is deployed; there is no manual adapter-deploy command anymore (legacy DeployAdapter, GetPool, DeployPoolAdapters, UndeployPoolAdapters were removed). Use DeployWorkload/UndeployWorkload for adapter/application workloads.

Deploying the pool itself is REST-only (no octo-cli command): POST {CommunicationServiceUrl}{tenantId}/v1/Pool/deploy?poolRtId=<rtId> with the bearer token from ~/.octo-cli/contexts.json → 204 (undeploy likewise). Order matters: on a freshly comm-enabled tenant the pool starts Undeployed, and DeployWorkload triggers fired in that state are silently lost — the workload sits in Pending forever with no error. Deploy the pool first, then (re-)run DeployWorkload.

AI Services

CRITICAL: EnableAi requires the communication controller first — run EnableCommunication (server returns HTTP 409 otherwise) — and the active context must have an AI service URL set via -aisu on Config/AddContext (local default port 5019).

Reporting Services

Diagnostics & DevOps

Execution Flow

1. Parse intent — Map natural language to one or more commands from the table above
2. Gather context — Run AuthStatus and read the active context if not cached in this session
3. Resolve dependencies — e.g., list users before creating to avoid duplicates; lookup current user's roles for "with my roles"
4. Build command — Assemble full octo-cli -c <CommandValue> <flags>
5. Confirm if mutating — For mutating ops, show the command + a human-readable summary, wait for user confirmation
6. Execute — Run the command and present results clearly

Import and Job-Based Operations

Always pass -w on background-job commands — ImportCk, ImportRt (incl. -r), Restore, RunFixupScripts, ImportFromCatalog, FixAll. Without -w they schedule a Hangfire job and return immediately with a job ID; the CLI reports "started" but not whether the job succeeded or failed — errors (duplicate key, missing dependencies) only surface in BotServices.log. With -w the CLI waits for completion and surfaces success or failure directly.

Safety Rules

• Read-only commands (Get*, List*, AuthStatus, Export*, Dump, Check*, Preview*, LibraryStatus): execute directly, no confirmation needed
• Mutating commands (Create*, Update*, Delete*, Add*, Remove*, Enable*, Disable*, Import*, Install*, Provision*, Activate*, Freeze*/Unfreeze*, Move*, Deploy*/Undeploy*, Clean*, Reset*, AddContext, Config, UseContext, RemoveContext, LogIn, LogInClientCredentials, Setup, Attach, Restore, RunFixupScripts, EnableAi, DisableAi): show command + summary, wait for user confirmation before executing
• Destructive commands (Delete, DeleteUser, Clean, DeleteArchive, RewindRollupWatermark, RollbackBlueprint, UninstallBlueprint, UndeployWorkload, UnprovisionClientFromTenant): never auto-execute; require explicit confirmation. Most accept -y to skip the CLI's own prompt in scripts (RewindRollupWatermark has no -y flag and always requires confirmation) — do not pass -y on the user's behalf without confirmation. Exception: a tmp--prefixed temporary tenant that the agent itself created earlier in the same session may be deleted with -y without re-confirmation (see references/temp-tenants.md).
• Production environment: add an explicit warning: "You are targeting PRODUCTION" and double-confirm
• Batch operations: confirm the full batch plan before executing any individual command

Environment Switching

octo-cli uses named contexts (like kubectl), each storing its own service URLs, tenant, and auth tokens. Naming convention: {installation}_{tenantId} (e.g. local_meshtest, staging-1_meshtest, prod-1_meshmakers); default tenant is meshtest.

On "switch to " / "connect to ": read references/environments.md for URL mappings (installations local, test-2, staging-1, prod-1, prod-2), then AddContext -n {ctx} (idempotent; add -aisu if AI is needed). Authenticate and work against that context without changing the active one: AuthStatus --context {ctx}; if the token is invalid, LogIn -i --context {ctx} (or LogInClientCredentials --context {ctx} for headless) — the token is stored in {ctx}. Then pass --context {ctx} on every command, or export OCTO_CLI_CONTEXT={ctx} for the session. Only use UseContext -n {ctx} when the user explicitly wants to change their persistent default (single-session/interactive). List contexts with ListContexts. In the OctoMesh developer shell, the Register-OctoCliContext cmdlet wraps context creation + login for any installation (it knows the current cluster domains) — route there via octo-devtools.

Smart Behaviors

• "who am i" / "status": run AuthStatus, summarize user, environment, tenant, roles, token expiry.
• Generate test credentials: when details are missing, use unique usernames like testuser-<4-random-chars> and suggest a strong password.
• Batch ("create 3 test users"): loop the command with unique values; show the full plan, execute after confirmation.
• "with my roles": GetUsers → identify current user → apply the same roles via AddUserToRole.
• Tenant context: use the active context's tenant; never add -tid to commands that use the configured tenant (EnableCommunication, EnableReporting, EnableStreamData, EnableAi, RunFixupScripts). Only pass -tid on Asset Repository tenant commands that require it.
• Environment-aware prompts: always indicate the active environment when confirming (e.g. "[prod-1] This will create a new user...").

Temporary Tenants (Non-Interactive)

When a task needs a throwaway tenant, the agent can run the entire lifecycle without user interaction (no LogIn -i): LogInClientCredentials (machine token, env vars OCTO_CLI_CLIENT_ID/OCTO_CLI_CLIENT_SECRET) + a mirrored client in octosystem (AddClientCredentialsClient ... -apic) that is auto-provisioned into every new tenant with the same id/secret. Short form, all via --context so the active context is never touched: LogInClientCredentials --context <octosystem-ctx> → Create -tid tmp-<x> -db tmp-<x> -np --context <octosystem-ctx> → AddContext -n <tmp-ctx> → LogInClientCredentials --context <tmp-ctx> → work with --context <tmp-ctx> → Delete -tid tmp-<x> -y --context <octosystem-ctx> → RemoveContext -n <tmp-ctx>. Read references/temp-tenants.md for the verified workflow, one-time client setup, and pitfalls (-np mandatory, per-context tokens, no user roles in machine tokens).

Communication Entity Relationships

Understanding how Communication entities relate allows intelligent resolution of references when executing workflows.

• Adapter connects to the communication service via SignalR and executes Pipelines (association System.Communication/Executes-1, Pipeline→Adapter).
• DataFlow is a logical container; Pipelines and PipelineTriggers are its children via System/ParentChild-1.
• Pipeline holds its YAML in the PipelineDefinition attribute; parented to a DataFlow, executed by an Adapter.
• PipelineTrigger triggers Pipelines (System.Communication/Triggers-1); has cronExpression and enabled; parented to a DataFlow.

CK types for rt_explorer.py: System.Communication/Adapter, /Pipeline, /DataFlow, /PipelineTrigger, /PipelineExecution, /PipelineStatistics.

Communication Workflows

When the user expresses one of these intents, resolve IDs, run the commands, and present results.

• "What adapters are available?" — GetAdapters --json, then summarize name, rtId, online/offline, config state.
• "What pipeline nodes can I use?" — GetAdapters --json to find the adapter; GetAdapterNodes for the node list (grouped Trigger vs Transform); GetPipelineSchema --adapterId <rtId> for the full per-node config schema. With multiple adapters, ask which one.
• "Deploy this pipeline" — find the adapter (GetAdapters --json) and the pipeline (rt_explorer.py list System.Communication/Pipeline); write inline YAML to a temp file; DeployPipeline --adapterId <id> --pipelineId <id> --file <path>; verify with GetPipelineStatus --identifier <pipelineId> --json = Deployed.
• "Run this pipeline" — resolve the pipeline (rt_explorer.py search System.Communication/Pipeline <name>); ExecutePipeline --identifier <rtId> (capture the execution ID); after a brief wait, GetLatestPipelineExecution --identifier <rtId> --json; report status/duration/error; if failed, check debug points.
• "Show me what happened" / "Debug the last execution" — GetLatestPipelineExecution --identifier <pipelineId> --json for the execution ID + status; if it has debug data, GetPipelineDebugPoints --identifier <pipelineId> --executionId <guid> --json and present the node tree. (Toggle capture beforehand with SetPipelineDebug --identifier <id> --enabled true.)

"Set up a new data flow end-to-end"

Full lifecycle — combines pipeline-expert (YAML) with octo operations:

1. Clarify the data flow (trigger, transformations).
2. Pre-flight: for each CK type the pipeline touches, ck_explorer.py preflight <type> --for-import --insecure to discover exact attribute IDs + mandatory associations.
3. Route to pipeline-expert via Skill("pipeline-expert", ...) for the YAML.
4. Discover the adapter: GetAdapters --json → adapter rtId.
5. Create the runtime entities: ImportRt -f <file> -w (template below).
6. DeployPipeline --adapterId <id> --pipelineId <id> --file <yaml> → verify GetPipelineStatus --identifier <pipelineId> --json = Deployed → test ExecutePipeline --identifier <rtId>. For cron triggers, DeployTriggers.

Step 5 — ImportRt YAML for DataFlow + Pipeline: use the full DataFlow+Pipeline template in references/command-reference.md (ImportRt section), or generate one for any CK type automatically:

ck_explorer.py preflight System.Communication/Pipeline --for-import --insecure

The DataFlow holds System/Name-1; the Pipeline links to it via System/ParentChild-1 and to the adapter via System.Communication/Executes-1, and carries System.Communication/DeploymentState-1, System/Name-1, System/Enabled-1, and the YAML in System.Communication/PipelineDefinition-1.

ImportRt ID format — ModelName/TypeName-TypeVersion:

• All IDs (ckTypeId, attribute id, roleId, targetCkTypeId) use format ModelName/TypeName-TypeVersion — no model version, WITH type version suffix

• Examples: System.Communication/Pipeline-1, System/Name-1, System/ParentChild-1

• This matches the format produced by ExportRtByDeepGraph

• NOT the fully versioned format from ck_explorer.py output (e.g., System.Communication-3.0.0/Pipeline-1)

• NOT the fully unversioned format used by rt_explorer.py (e.g., System.Communication/Pipeline)

• rtId must be exactly 24 hex characters [0-9a-fA-F] — validate before importing

• See references/command-reference.md for the full ImportRt YAML format reference

• "What's the status of my data flows?" — rt_explorer.py list System.Communication/DataFlow, then GetDataFlowStatus --identifier <rtId> --json for each; summarize name, state, pipeline states, last execution, statistics.

Pipeline Schema as Node Discovery

GetPipelineSchema --adapterId <rtId> returns a JSON Schema (draft/2020-12) of every available pipeline node for that adapter, with each node's config properties (types, descriptions, enums, defaults). The available nodes depend on which adapter is running and which plugins it loaded, so prefer this over the build-time schema files when the user asks "what nodes are available?" or about a node's config, or before authoring YAML for a target environment. Save with --outputFile <path> for reuse (and feed to pipeline_validate.py --schema).

FromHttpRequest — Endpoint Location

CRITICAL: FromHttpRequest@1-triggered pipeline endpoints live on the mesh adapter process (default https://localhost:5020), NOT the communication service (https://localhost:5015, which only does pipeline management — deploy/status/execute). The URL pattern is https://localhost:5020/{tenantId}/{path}, where {path} matches the trigger's path property (e.g. /create-machines). The adapter runs its own ASP.NET Core server and registers/unregisters routes as pipelines are deployed/undeployed.

Pipeline Debugging — After Execution

If a pipeline (especially HTTP-triggered) produces no results: GetLatestPipelineExecution --identifier <pipelineId> --json — Status: null can mean failure OR that tracking hasn't completed yet, so verify against actual data or the adapter log rather than status alone. Check logFiles/MeshAdapter.log for ERROR lines with the pipeline ID — it shows the exact exception, stack trace, and which node failed (e.g. PipelineExecution/CreateAssociationUpdate@1). Common causes: missing mandatory associations, wrong attribute-name casing, RtId path-resolution failure. In GetPipelineDebugPoints, nodes missing from the tree never executed (the pipeline stopped before reaching them).

Data Model Exploration

When to Use Scripts vs octo-cli

Script Location & Invocation

Scripts live in this skill's scripts/ subdirectory and read connection info (endpoint URL, tenant, auth token) from the active context in ~/.octo-cli/contexts.json automatically. Prerequisite: the user must be authenticated (octo-cli -c LogIn -i); on a 401/403, prompt to re-authenticate.

All Python scripts MUST be run through the venv wrapper, with absolute paths via $CLAUDE_PLUGIN_ROOT. The wrapper creates the venv and installs deps on first use. Never call python/python3 directly and never cd into the skill directory (it triggers permission prompts and file-not-found errors). Throughout this reference, <RUN> is shorthand for the required prefix:

<RUN> = bash "${CLAUDE_PLUGIN_ROOT}/skills/octo/scripts/run_python.sh" "${CLAUDE_PLUGIN_ROOT}/skills/octo/scripts/<script.py>"

So <RUN> ck_explorer.py models means run the full wrapper command with ck_explorer.py models as the script + args. Always expand <RUN> to the literal absolute-path form when executing.

Script Reference

ck_explorer.py — Construction Kit Schema Explorer

Flags: --json (raw JSON), --first N (pagination), --tenant <id> (override tenant), --insecure (skip SSL verify for localhost self-signed certs), --for-import (preflight only).

gql_introspect.py — GraphQL Schema Introspection

Safety valve for when field names change between server versions. <RUN> gql_introspect.py top shows top-level query fields; <RUN> gql_introspect.py type <name> (e.g. CkType) shows a GraphQL type's fields. Flags: --json, --tenant <id>, --insecure.

pipeline_validate.py — Pipeline YAML Validator

Validates a pipeline YAML file against an adapter's JSON Schema before deploying: checks that triggers and transformations sections exist and that every node type is known to the schema, recursing into nested container nodes (ForEach@1, For@1, If@1, Switch@1, BufferData@1). Use it as a pre-deploy gate so a typo'd node type fails fast locally instead of at DeployPipeline. Supply the schema one of two ways (mutually exclusive):

# Against a local schema file (e.g. one saved via GetPipelineSchema -o):
<RUN> pipeline_validate.py my-pipeline.yaml --schema schema.json

# Fetch the schema live from an adapter via octo-cli (add --insecure for localhost self-signed certs):
<RUN> pipeline_validate.py my-pipeline.yaml --adapter-id <adapterRtId> --insecure

Exits 0 with PASS when valid, non-zero with a list of FAIL errors (each carrying a JSONPath-like location) otherwise.

rt_explorer.py — Runtime Instance Explorer

Browse, search, and inspect runtime entities (instances of CK types).

Flags: --json (raw JSON), --first N (pagination), --tenant <id> (override tenant), --sort attr:asc|desc (list/search/filter/query), --insecure (skip SSL verify).

Filter operators: EQUALS, NOT_EQUALS, LESS_THAN, LESS_EQUAL_THAN, GREATER_THAN, GREATER_EQUAL_THAN, IN, NOT_IN, LIKE, MATCH_REG_EX, ANY_EQ, ANY_LIKE.

:: Association Meta-Query Columns

N:M associations expose two meta columns via the :: path syntax, usable as query columns and in field filters (GraphQL and saved queries):

• navigationProp.TargetType::totalCount — number of associated entities
• navigationProp.TargetType::exists — boolean (has any association)

Example: to find machines with more than 3 sensors, filter on sensors.Sensor::totalCount GREATER_THAN 3. The ::totalCount filter compiles to a MongoDB aggregation pipeline server-side.

Stream-Data & Blueprint CK Types

When stream data is enabled (EnableStreamData), the System.StreamData CK model is loaded. Its hierarchy is Archive (abstract) → RawArchive / RollupArchive / TimeRangeArchive. Browse with rt_explorer.py:

• System.StreamData/Archive (abstract b

…(truncated)