cloud-core

cloud-core

When to use this skill

• The user asks to install, upgrade, or verify snctl.
• The user mentions snctl auth login, auth whoami, auth logout, or service-account activation/export.
• The user wants to switch organization, service context, or Pulsar instance/cluster via snctl context.
• The user asks what API resources snctl exposes, or needs to inspect generic snctl get / snctl describe output.
• The user reports an auth, config, or context error surfaced by another skill.
• The user wants to fetch logs via snctl logs.

Execution base

Prefer StreamNative Cloud remote MCP when agent runtime exposes it; see references/remote-mcp.md. Use sncloud_context_*, sncloud_resource_catalog, sncloud_resource_schema, and sncloud_logs for remote context/discovery/log workflows. Use snctl fallback for local install/config/auth/token and service-account key export/activation.

Prerequisites check

If remote MCP is available, start with sncloud_context_whoami; use sncloud_context_available_clusters / sncloud_context_use_cluster for cluster-scoped work. After a successful cluster switch, output MCP_TOOLS_REFRESH_REQUIRED instance=<instanceName> cluster=<clusterName> and stop the current turn so the runner/runtime can refresh MCP tools before data-plane calls. If using snctl, run these commands and handle failures:

• snctl version --client — if "command not found", open references/install.md and guide the user through install.
• snctl config get — if config is missing, guide the user through snctl config init.
• snctl auth whoami — if unauthenticated, open references/auth-flows.md and pick the right login path (user vs service account).

Mental model

Remote MCP server is public preview and disabled by default. Users must manually enable org-level MCP and each cluster-level MCP endpoint in StreamNative Cloud UI; newly created clusters keep cluster-level MCP disabled until UI enablement. Remote MCP org-level sessions expose StreamNative Cloud context, catalog/schema, domain control-plane, and feature-gated cluster tools; cluster tools require a fixed cluster endpoint or successful sncloud_context_use_cluster, which only works when cluster-level MCP is enabled for the target cluster. After sncloud_context_use_cluster succeeds, emit the exact sentinel MCP_TOOLS_REFRESH_REQUIRED instance=<instanceName> cluster=<clusterName> because selected cluster context changes the session-scoped tool surface; the runner/runtime must refresh/reconnect MCP tools and resume before data-plane tools are visible. snctl is a kubectl-flavored CLI that talks to StreamNative Cloud's control plane. Every action happens in the context of an organization (namespace-style scope) plus optionally a service context (a selected Pulsar instance/cluster for data-plane operations). Auth is OIDC-based for users; service-account auth uses a downloaded JSON key, exchanged for a short-lived token on each call. Output formats follow kubectl conventions (-o yaml|json|name|jsonpath=...).

Primary workflows

W1. First-time install and login

# Install (macOS/Linux)
curl -fsSL https://downloads.streamnative.cloud/snctl/install.sh | sh
# Initialize config
snctl config init
# Log in as a user (opens browser)
snctl auth login
# Verify
snctl auth whoami
snctl config get

W2. Switch organization

snctl config set --organization <org-name>
snctl config get

W3. Service-account credentials (automation)

# Export a key for an existing service account
snctl auth export-service-account <sa-name> --organization <org> -O <org> --key-file ./sa.json
# Activate the key on the machine running the agent
snctl auth activate-service-account --key-file ./sa.json
# Verify
snctl auth whoami

W4. Select a service context (for data-plane work)

Remote MCP route: sncloud_context_available_clusters → sncloud_context_use_cluster; after a successful sncloud_context_use_cluster, output exactly MCP_TOOLS_REFRESH_REQUIRED instance=<instanceName> cluster=<clusterName> and stop before invoking newly exposed cluster tools; reset with sncloud_context_reset when switching.

snctl route:

# List available contexts (instance/cluster pairs visible to the current identity)
snctl context
# Use a specific cluster
snctl context use <cluster-name>
snctl context current

W5. Inspect available API resources

Remote MCP route: use sncloud_resource_catalog for domain/kind inventory, then sncloud_resource_schema for manifest summaries/examples/runtime schema.

snctl route:

snctl api-resources
snctl api-resources -o wide

W6. Fetch logs for a resource

Remote MCP route: select cluster if needed, then use sncloud_logs.

snctl route:

snctl logs <pod-or-resource> --organization <org>

W7. Get a short-lived bearer token (for REST API calls)

snctl auth get-token

Common flags and output conventions

• Always pass -o yaml|json|name|jsonpath=... when the agent needs to parse output — never regex a plain-text table.
• Always pass --organization <org> explicitly for org-scoped scripted flows; do not rely on current context. Avoid kubectl-style -n in snctl smoke/docs because current snctl builds may reject it for Cloud resource commands.
• For destructive actions (snctl delete, snctl revoke), state the exact resource to the user and require explicit confirmation before running.

Reference index

• references/remote-mcp.md — remote MCP tool families, session model, mutation workflow, limitations.
• references/install.md — all install methods (script, homebrew, manual, offline).
• references/auth-flows.md — user login, service-account activation, OIDC external providers.
• references/output-formats.md — -o flag details and jsonpath recipes.
• references/troubleshooting.md — common auth/config/context errors and recovery.

Pitfalls and gotchas

• Remote MCP write tools require JSON-string manifests and dry-run-first workflow; do not pass YAML or object values.
• For remote MCP server-side/transient failures, retry once when safe; if retry also fails, stop and expose tool name, operation, resource, original error, retry error, and safest next action to the user.
• Do not blindly retry ambiguous dry_run=false apply/delete failures; read current resource state first, then retry only if safe/idempotent.
• Remote MCP org-level public contract is domain-scoped; do not use generic sncloud_resources_* names.
• Remote MCP server is public preview and disabled by default. Org-level MCP and cluster-level MCP must be enabled separately in StreamNative Cloud UI.
• sncloud_context_use_cluster requires cluster-level MCP enabled on the target cluster; new clusters may not enable it automatically. After a successful cluster switch, emit MCP_TOOLS_REFRESH_REQUIRED instance=<instanceName> cluster=<clusterName> and wait for runner/runtime refresh because the session-scoped tool surface has changed. ToolSearch is not a refresh substitute. May need to refresh the tool page until cluster-level tools show up.
• snctl auth login opens a browser; on headless machines use --headless for device-code flow.
• Service-account key files contain secrets; never commit them. Activation writes credentials to ~/.snctl/.
• snctl context use affects the local config only. For one-off calls prefer the --as-service-account / --use-service-account flags.
• snctl config set --organization changes the default org for all subsequent commands; verify with snctl config get before running destructive operations.
• Tokens from snctl auth get-token are short-lived (~1h). Re-run on expiry; do not embed in long-lived scripts.
• When another skill reports an auth error, the remediation lives here — do not try to work around it in the originating skill.