corectl

corectl is the command-line client for the Core Platform API. Core Platform Portal (or Portal) is the web client of the same API. The client supports login, context selection, cluster listing, agent lifecycle operations and direct kubeconfig generation using existing local credentials. Kubernetes credential provisioning and application creation are not currently supported.

Install

Trust the Core Platform Homebrew tap and install coreplatform to get corectl, the Core Platform CLI tool, and its dependencies:


brew trust coreeng/public
brew install coreeng/public/coreplatform
corectl version

Update the CLI with brew update && brew upgrade corectl.

Download a specific version manually

Releases are published as public packages at ghcr.io/coreeng/corectl. corectl has its own release versions and production promotion, independent of the Core Platform API, Portal and agents. Use a production-promoted corectl version in place of VERSION below. The Homebrew formula records the currently promoted version. PR previews carry a commit SHA suffix; merges publish versioned release candidates. Both are public after successful corectl checks, so you can use them in the same download command without waiting for production promotion. Promotion selects an existing tested candidate without rebuilding it. The Core Platform API and Auth services must support the native CLI before login is available.

With ORAS installed, download the package without a GitHub account:


oras pull ghcr.io/coreeng/corectl:VERSION -o corectl-download
cd corectl-download

Verify the downloaded files before extracting them:


# macOS
shasum -a 256 -c checksums_VERSION.txt
 
# Linux
sha256sum -c checksums_VERSION.txt

Choose the archive for your OS and CPU: darwin or linux, and arm64 or x86_64. For example, on an Apple Silicon Mac:


tar -xzf corectl_VERSION_darwin_arm64.tar.gz
./corectl version
./corectl auth login
./corectl get clusters

Add the directory containing the extracted binary to your PATH. The examples below use corectl. Compatible CLI and API releases can differ, allowing one CLI to work with production and integration.

Install and manage cluster agents

Register the cluster in Portal, then copy its suggested corectl agent install command. Sign in to that Portal instance first:


corectl auth login --url https://portal.example.com
corectl agent install customer-dev --kube-context my-kubernetes-context

Your account needs administrator access in the selected Portal context and sufficient Kubernetes permissions to manage the Cluster System release, including its namespace and RBAC. Provide an existing working kubeconfig. corectl embeds Helm and Kubernetes clients; you do not need Helm or kubectl installed. Any authentication helper referenced by your kubeconfig, such as a cloud credential plugin, must still be available and authenticated. corectl does not provision cloud credentials or Kubernetes access. Kubernetes API endpoints must use HTTPS, except for localhost and loopback IP addresses. Server URLs must not contain embedded credentials, query parameters, or fragments.

--kubeconfig PATH selects a configuration file; otherwise corectl uses KUBECONFIG or ~/.kube/config. The initial interactive command asks you to choose a Kubernetes context when --kube-context is omitted. Noninteractive runs need an explicit context or an association saved by a previous successful operation. corectl never changes your kubeconfig’s current context.

Portal commands include --context CONTEXT_NAME, using the full context key from login, for example:


corectl agent upgrade customer-dev --context core-platform/engineering-test

This selects the intended Core Platform context for that command without changing your saved selection. If the context is unavailable, sign in to that Portal instance and context first. --context is separate from --kube-context, which identifies the Kubernetes cluster. Release ownership checks use immutable internal identities.

After a successful operation, corectl remembers the nonsecret Kubernetes context and kubeconfig path for that instance, context and cluster on your computer:


corectl agent enable-management customer-dev
corectl agent upgrade customer-dev
corectl agent repair customer-dev
corectl agent uninstall customer-dev

install installs or re-enrolls the Runtime Agent.
enable-management installs or re-enrolls the Control Agent. A fresh Runtime Agent is required. corectl performs both managed bootstrap stages when needed.
upgrade uses the version selected by Portal and preserves agent credentials.
repair restores a missing or broken release using fresh enrollment tokens for all agents required by the cluster’s current mode. Context resources are preserved.
uninstall removes the Cluster System Helm release and waits up to five minutes for chart resources to be deleted. If deletion fails or times out, fix the reported issue and retry; corectl retains the release history and local association. Portal registration and context resources remain; disconnect the registration separately in Portal.

corectl checks Kubernetes access and existing release ownership before requesting enrollment tokens. Tokens are obtained at execution time and are not included in copied commands or corectl’s local metadata. The installed Helm release and chart-managed Secrets retain the same credential behavior as a manual Helm installation. Portal shows enrollment progress and confirms a fresh agent report.

If an operation fails, corectl reports the stage that failed. Fix the reported access or release issue and retry; use repair when the release or credential Secrets are missing. Interrupted or failed Helm operations may leave a release requiring inspection before retrying. There is no automatic rollback of enrollment credentials.

Before disconnecting a registration, retain Portal’s cleanup command. It works after the registration is deleted and does not need a Portal login:


corectl agent uninstall --release-name cp-0123456789abcdef01234567 --kube-context my-kubernetes-context

Published charts can be installed on any reachable Kubernetes cluster, including k3d, using its existing kubeconfig. Source-built chartVersion=local instances continue to use the repository’s local Make and image-import workflow.


corectl auth login
corectl get clusters

Login opens a browser on your machine and uses portal.coreplatform.io by default. Sign in and approve access for corectl, even if your browser is already signed in. You can decline without changing your saved contexts. After browser sign-in, the corectl next steps page opens. Return to your terminal for confirmation that the API accepted your login and credentials were saved.

The confirmation shows the context key followed by the readable context name:


Logged in to core-platform/engineering-test (Engineering Test) as user@example.com

An additional Current context: ... line appears only when your saved default context differs from the context you just signed in to. For example, signing in with corectl auth login --context CONTEXT_NAME preserves your saved default and reports it separately when it differs.

If you have one context, it is selected automatically. Most users can continue with get clusters without managing contexts. Check your identity with corectl auth whoami, or sign out with corectl auth logout.

auth whoami shows the effective context key, context display name and account:


CONTEXT                          DISPLAY NAME      USER
core-platform/engineering-test   Engineering Test  user@example.com

Its JSON and YAML output include context, displayName, instance and user. Context overrides apply to that invocation without changing the saved current context.

Tokens are stored in macOS Keychain or Linux Secret Service and refreshed automatically. On Linux, an unlocked Secret Service session must be available; tokens are never stored as plaintext files.

If browser opening fails, corectl prints the URL so you can open it yourself. Use corectl auth login --no-browser to always print the URL without opening it. Open it in a browser on the same machine: the callback uses a local loopback port. This is not a remote-shell device login flow.

If login cannot start, corectl reports the instance URL and HTTP status. Check that you selected the intended instance; if the problem persists, share the error with your platform team. Deleting local credentials does not fix this error.

Output formats

get clusters, config get-contexts, and auth whoami display tables by default and support -o json and -o yaml for structured output:


corectl get clusters -o json
corectl config get-contexts -o yaml
corectl auth whoami -o json

Cluster tables use NAME, TIER, VERSION, TYPE, REGION, and STATUS, in that order. Cluster listing follows the same context visibility as Portal, including catalogue entries without a connected agent. Type and region come from the API; unavailable values are displayed as -. Reported cluster IDs remain available in JSON/YAML under clusterRuntime.clusterId and clusterControl.clusterId.

VERSION shows the version reported by the configured agents. It is Mixed when fresh Runtime Agent and Control Agent reports disagree, and Unknown when a configured agent has no fresh version report. The value comes from Portal; listing clusters does not require kubeconfig access or contact the Kubernetes cluster. Tables shorten trailing full commit hashes to five characters, matching Portal. JSON and YAML retain full versions and include platformRegion, installedVersion and each available agent’s agentVersion and heartbeat freshness under clusterRuntime and clusterControl.

Above a cluster table, corectl identifies the effective destination:


Context: core-platform/engineering-test (Engineering Test)

This line reflects command overrides and is written to stderr. JSON and YAML include context, displayName and instance in the output instead of this heading.

Diagnostic output

The global -v / --verbose flag adds diagnostic details on stderr. For agent operations, these include chart versions, Helm stages, release identifiers and confirmation that connection metadata was captured and published. The flag works before or after the command:


corectl -v agent upgrade customer-dev
corectl agent repair customer-dev --verbose

Command results stay on stdout. Verbosity does not change the result data or format, so -o json and -o yaml remain valid structured output. To save results without diagnostics, redirect stdout separately:


corectl --verbose get clusters -o json > clusters.json

Without --verbose, agent commands show concise progress and results. Warnings, prompts and recovery instructions are always shown. Agent operations still identify the selected Kubernetes target, and offline uninstall always identifies its release.

Work with multiple contexts

If you belong to multiple contexts, list them and select where to work:


corectl config get-contexts
corectl config use-context core-platform/engineering-test
corectl get clusters

Selection uses the full context key, such as core-platform/engineering-test. Display names such as Engineering Test are labels, not command selectors.

Switching confirms the exact context key and display label:


Switched to context "core-platform/engineering-test" (Engineering Test).

Selecting a context may open Auth in your browser to obtain its credentials. If a script needs a context with no usable credentials, it fails with a login command. An unavailable context never silently falls back to another one.

To use another context for one command without changing the saved default:


corectl get clusters --context core-platform/engineering

CURRENT markers in context tables identify the saved default, even when a resource command uses an override. To print just the saved context key:


corectl config current-context

Work with additional instances

A context selects where you work in a Core Platform instance. Most users only need the hosted service. If you have access to another instance, sign in using its URL, then use the context names printed by get-contexts:


corectl auth login --url https://portal.example.com
corectl config get-contexts
corectl config use-context core-platform/engineering-test
corectl get clusters --context example-platform/engineering-test

The URL and context names above are examples; use those supplied for your instance. Instances retain separate credentials. config use-context saves a new default. Resource-command --context overrides apply to that invocation only. Login normally selects the context you signed in to. An explicit auth login --context CONTEXT_NAME signs in to that context while preserving the saved default. On first login, when there is no default, the authenticated context becomes the default.

To bootstrap a specific context in a new instance, supply both its URL and key:


corectl auth login --url https://customer.example.com --context customer/engineering

The discovered instance must match customer, and your authenticated memberships must include engineering. Without --url, an explicit context must already be known locally; corectl never infers an instance URL from its name.

Context keys and display names come from the latest successful login. Refreshing another context’s older session does not replace them. A new login picks up display-name changes without changing context identity or keys; a short-name change updates the context key.

List saved contexts


corectl config get-contexts
corectl config get-contexts -o wide
corectl config get-contexts --offline --no-headers
corectl config get-contexts -o name

The listing includes all memberships learned from successful logins, even when a context has no saved credentials. It does not discover unknown instances or new memberships until you sign in again.

The default table has CURRENT, NAME, DISPLAY NAME, and AUTH columns. NAME is the exact context key; DISPLAY NAME is its readable display name. -o wide adds the saved account in USER. --no-headers omits headers from default and wide tables.

By default, get-contexts verifies saved logins against each instance and refreshes tokens only when needed. It never opens a browser or changes your selected context. Failed checks retain saved credentials. Table labels and structured authStatus values differ:

Meaning	Table `AUTH`	JSON/YAML `authStatus`
Login verified	`signed in`	`logged in`
Credentials missing or rejected	`not signed in`	`login required`
Verification could not complete	`unavailable`	`unavailable`
Saved credentials have not been checked	`not checked`	`not checked`

Use --offline to list local metadata without accessing credentials or the network; saved logins then show not checked. Online checks have a five-second network timeout per instance, adjustable with --timeout 10s, and check up to four instances concurrently.

-o name prints only sorted context keys, one per line. It always uses local metadata, without accessing credentials or the network, and prints nothing when there are no contexts. -o wide, -o name, and --no-headers are available on config get-contexts; resource listings retain table, JSON, and YAML output.

Structured context rows include name, current, instance, displayName, user, credentialsSaved, and authStatus. name is the full context key; displayName supplies the readable label. credentialsSaved indicates local storage, not successful authentication. --no-headers does not apply to JSON, YAML, or names-only output.

Sign out


corectl auth logout

Logout clears all context credentials for the selected instance while retaining its saved contexts. To select another instance for logout, use corectl auth logout --context CONTEXT_NAME. If there is no saved login to clear, it succeeds with Already logged out. Other instances remain signed in.

If remote revocation is unavailable, corectl reports that separately; previously issued access tokens can remain valid until they expire. If instances share the same Auth session, remote revocation is skipped and reported to preserve the other instance’s login. Logout does not modify Kubernetes credentials.

Check the client version


corectl version
corectl version -o json
corectl version -o yaml

The default output is one line, for example:


corectl 0.8.0 (0123456) darwin/arm64 go1.27.0

It shows the release version, short source commit, OS/architecture, and Go version. A local build with uncommitted changes adds -dirty to the commit. Unknown Git tree state adds -unknown to a known commit; a missing commit is shown as unknown. JSON and YAML expose version, the full commit, platform, goVersion, and gitTreeState (clean, dirty, or unknown). Version inspection needs no login or network access.

Shell completion and help

Homebrew installs bash, zsh and fish completions alongside corectl. With Homebrew shell completion configured, open a new shell after installing or upgrading to use them.

For zsh, ensure eval "$(brew shellenv)" runs before completion initialization. If your shell configuration or framework does not already call compinit, add these lines to ~/.zshrc after your Homebrew environment setup:


autoload -Uz compinit
compinit

Homebrew’s fish discovers the installed completions automatically. Bash needs Homebrew’s bash-completion setup linked above.

For local builds, manual installations, or PowerShell, generate shell completion code by specifying bash, zsh, fish, or powershell:


corectl completion zsh

The generated code must be loaded into your shell to enable completion. For zsh:


autoload -Uz compinit && compinit
source <(corectl completion zsh)

See corectl completion --help for current-session examples for the other shells.

Context completion inserts exact selectors with readable display labels. It reads saved metadata only, without accessing credentials or the network. Suggestions include all locally known contexts. A supplied auth login --url filters them to that known destination; an unknown URL has no suggestions until login discovers its memberships.

--kube-context completes Kubernetes context names from --kubeconfig, the merged files in KUBECONFIG, or the default ~/.kube/config. It filters by the prefix you type and does not contact Kubernetes, run credential helpers, or change the current context. To complete from a specific file, put --kubeconfig PATH before --kube-context.

Root help lists available commands before usage. Individual command help includes examples and supported flags:


corectl --help
corectl auth login --help
corectl config get-contexts --help

Configuration storage

On both macOS and Linux, corectl stores its configuration in ~/.config/corectl/config.json. Set XDG_CONFIG_HOME to an absolute directory to use $XDG_CONFIG_HOME/corectl/config.json instead. Relative values are ignored.

Saved instances, contexts and the selected context live in that file; login tokens remain in the OS credential store.

Authentication security

corectl opens your system browser for Keycloak login and explicit approval. It uses Authorization Code flow with S256 PKCE and binds refresh tokens to a key stored with the login in your OS credential store. Refresh and revocation require a DPoP proof; copying a refresh token alone is insufficient. Logins created before this protection require corectl auth login again.

Portal authenticates its own token requests with a server-only signing key. Both clients use the same API authorization boundaries, enforced using verified roles and immutable internal Tenant identity. Context selects the instance and customer scope to access; its name and display label do not grant access or determine ownership. Access tokens are still short-lived Bearer tokens; logout prevents further refresh but does not immediately invalidate every issued access token. See the Auth security documentation for the RFC mapping, deployment requirements and limits.

Configure kubectl for a registered cluster

Sign in to Core Platform, then use the cluster’s short name. In Portal, open the cluster and choose Set up kubectl to find the connection command and applicable local credential guidance.


corectl connect gcp-dev --context core-platform/cecg

The command creates and selects Kubernetes context core-platform/cecg/gcp-dev. --context selects the Core Platform context for this invocation. It does not select a source Kubernetes context or change your saved Core Platform default. Qualified cluster arguments such as cecg/gcp-dev are not supported.

You must already have cloud/Kubernetes credentials and network access to the API endpoint directly, or use Core Platform VPN when the cluster has a ready managed connector. Connect verifies TLS and authenticated identity with SelfSubjectReview before writing. Success does not grant additional Kubernetes permissions or guarantee authorization for every subsequent operation.

Option	Behavior
`--kubeconfig PATH`	Write an isolated destination; otherwise use standard `KUBECONFIG` / `~/.kube/config` loading rules
`--no-switch`	Preserve Kubernetes current-context
`--proxy-url URL`	Use an existing HTTP, HTTPS or SOCKS5 proxy for Kubernetes verification and save it only in the local kubeconfig
`--namespace NAME`	Set a namespace; otherwise preserve the existing value
`--timeout 2m`	Bound generation and verification
`--non-interactive`	Never prompt or initiate login; no TTY also implies this behavior
`--client-certificate PATH --client-key PATH`	Use your own local certificate and private key files
`-o json` or `-o yaml`	Print context, destination, selection and verification result without credentials

Existing unrelated configuration is retained. Same-name entries owned by another identity or registration are not overwritten. An ambiguous multi-file destination requires an explicit --kubeconfig. Failed generation or verification leaves the destination unchanged. Connect does not change administrator installation associations.

If an instance or context rename would rename your selected Kubernetes context, --no-switch stops without changing kubeconfig. Select another context first, or retry without --no-switch to rename and select the updated context.

For managed clusters, corectl first verifies direct access. If the network dial fails, it asks Portal to authorize a cluster-scoped VPN session and starts a background worker. TLS and Kubernetes authentication failures do not trigger VPN fallback. The worker exposes an authenticated loopback proxy and keeps the original API endpoint and TLS verification in kubeconfig. Kubernetes credentials are still yours to supply; VPN access does not grant Kubernetes permissions.


corectl connect gcp-dev
corectl get clusters
corectl disconnect gcp-dev

To require VPN even when the Kubernetes endpoint is publicly reachable, use:


corectl connect gcp-dev --vpn

--vpn skips the direct Kubernetes access check, verifies access through the managed tunnel, and saves that route in kubeconfig. It fails if VPN access is unavailable; it never falls back to a direct connection. It cannot be combined with --proxy-url. This is useful for testing VPN access without changing the cluster’s endpoint.

The TUNNEL column is local to this machine. It reports Ready or Reconnecting from the running worker; it is separate from the API-owned cluster status. disconnect stops the local worker and revokes its session, leaving kubeconfig unchanged. Run connect again before using a context whose VPN has been stopped.

The worker reconnects after ordinary network interruptions while its Portal lease remains valid. If authorization expires, run connect again. Workstations and CI use the same commands: authenticate corectl first, use --non-interactive and an explicit --kubeconfig in CI, and call disconnect during runner cleanup. No system Tailscale client or privileged host network configuration is required.

If Kubernetes access requires a proxy that you already run, supply its local URL:


corectl connect sandbox-aws --proxy-url http://localhost:54882

Subsequent kubectl commands use the saved proxy. An explicitly supplied proxy remains caller-managed, and TLS verification remains enabled. The proxy URL is never uploaded to Core Platform. This option configures Kubernetes access; cloud CLIs and authentication helpers continue to use their own network configuration. SOCKS5 has Kubernetes limitations for SPDY streaming operations such as exec, attach and port-forward.

Supply --proxy-url again when reconnecting through that proxy. Omitting it writes a direct connection when reachable, otherwise using the managed VPN fallback. Normal Kubernetes HTTP/HTTPS environment proxy settings still apply.

Provider requirements

Provider integrations use existing local credentials and installed tools. They do not install tools or run login commands for you.

GKE: gcloud and gke-gcloud-auth-plugin; cluster metadata includes project, zone/region and DNS, external-IP or internal-IP endpoint selection.
EKS: AWS CLI; --aws-profile selects local credentials, --aws-role-arn selects the kubectl authentication role, and --aws-describe-role-arn selects a role used only for retrieving cluster metadata. These choices stay local.
AKS: Azure CLI and kubelogin, with an existing Azure CLI login to the registered Azure cloud. User credentials are used, never admin credentials.
k3d: on the machine running the cluster, corectl calls k3d kubeconfig get using the recorded local cluster name. This reads the cluster’s existing administrator certificate and key and saves them only in your local kubeconfig after verification. The k3d CLI and its local container runtime must be available. Supplying --client-certificate and --client-key uses those credentials instead and does not call k3d. A localhost endpoint works only on the machine exposing that endpoint. Another machine needs a reachable address whose TLS certificate validates and its own credentials.

Provider endpoint or CA changes require an administrator to refresh metadata. Connect does not silently replace server trust with newly discovered values. GCP remains the production baseline; EKS and AKS are experimental and require validation against the intended provider environment before operational use.

Configure or refresh existing registrations

An administrator with an existing Cluster System installation can backfill public connection metadata without reinstalling agents or rotating enrollment tokens:


corectl agent update-connection-info gcp-dev \
  --context core-platform/cecg \
  --kube-context existing-admin-context

Installation capture and agent update-connection-info use any proxy already set in that source kubeconfig for verification. They publish only cluster endpoint, TLS trust and provider details. Connecting users can use managed VPN fallback or supply their own proxy through connect --proxy-url.

--kubeconfig on this administrator command selects the source file. Missing or ambiguous discovery requires explicit provider identifiers. Missing identifiers for a selected provider can be entered interactively; automation supplies flags.


corectl agent update-connection-info gcp-dev --kube-context renamed-gke-context \
  --provider gke --gke-project my-project --gke-cluster gcp-dev \
  --gke-location europe-west2 --gke-location-type region --gke-endpoint external
 
corectl agent update-connection-info eks-dev --kube-context existing-eks \
  --provider eks --eks-cluster-arn arn:aws:eks:eu-west-2:123456789012:cluster/eks-dev
 
corectl agent update-connection-info aks-dev --kube-context existing-aks \
  --provider aks \
  --aks-resource-id /subscriptions/00000000-0000-4000-8000-000000000001/resourceGroups/platform/providers/Microsoft.ContainerService/managedClusters/aks-dev \
  --azure-cloud AzureCloud

GKE also supports --gke-endpoint dns and internal, and --gke-location-type zone. AKS accepts --azure-tenant-id when required by the authentication configuration. The selected provider locator must reproduce the administrator’s target and trust. Profiles, client certificates/keys, tokens, local proxy addresses and kubeconfig contents are never uploaded. A public server CA bundle or explicit system roots provide trust; insecure TLS is not an option.

New agent installations attempt this capture automatically. If discovery or publication fails, installation still completes and prints the strict backfill command. Existing registrations without metadata remain valid; this is not a cluster health failure. Upgrade the API before deploying the new CLI/UI surfaces. An older API produces an upgrade-required error for connection operations.

Isolated unattended use


corectl connect gcp-dev --context core-platform/cecg \
  --kubeconfig ./job-kubeconfig --non-interactive -o json
kubectl --kubeconfig ./job-kubeconfig get pods

An already authenticated Core Platform session and caller-local Kubernetes/cloud credentials are required. This prepares local configuration for automation; it supports the managed Kubernetes VPN described above, but does not implement GitHub/GitLab OIDC login, credential issuance or Pinniped. Use separate output files for independent jobs.

Upgrade to context-only selection

The Portal and CLI now use Context for your selected place to work. Update the CLI before copying commands from the updated Portal. The old workspace flag and commands have been removed without aliases; use --context CONTEXT_NAME, config get-contexts, and config use-context. JSON/YAML consumers must read the full selection from context (or name in context-list rows), with its readable label in displayName. The old workspace output object has been removed. Reload your shell completions after upgrading.

Existing login configuration and saved credentials remain valid. Local agent installation associations now use format version 2. If corectl rejects an old installations.json, back it up outside its active path under your corectl config directory. With the same registered cluster and verified Kubernetes target, run:


corectl agent install CLUSTER --context CONTEXT_NAME \
  --kubeconfig EXISTING_KUBECONFIG --kube-context EXISTING_KUBERNETES_CONTEXT

This re-enrols the existing installation and records its new association. It can renew agent credentials; verify the target before running it. Do not use --create-local to recover an existing local cluster. Keep its private kubeconfig.

Old generated connection ownership records are not adopted. Reconnect into a fresh destination and use that file explicitly:


corectl connect CLUSTER --context CONTEXT_NAME --kubeconfig NEW_KUBECONFIG

Review removal of obsolete generated entries separately. Never delete unrelated kubeconfig entries or recreate resources for this terminology change.