CLI Reference
The core binary (grpc/cmd/core, command tree in grpc/internal/cli) is the single control surface for the platform. Everything on this page was taken from the --help output of the binary built from this repository. Run core <command> --help for the authoritative text on your build.
Some older notes describe a
core fleet up|down|status command and a --mode fleet deploy. The built binary has neither: root.go registers no fleet command, and --mode accepts local or onhost only.Configuration
Resolution order (root.go, initViper): ./core.yaml, then ~/.core.yaml, then CORE_* environment variables (a . in a key becomes _), then flags. A missing config file is fine.
Global flags
| Flag | Default | Meaning |
|---|---|---|
--mode | local | local (multipass k0s, dev) or onhost (single-node k0s on this box) |
--face-repo | ../face | path to the sibling FACE repo |
--pulse-repo | ../pulse | path to the sibling PULSE repo |
--control-ctx | face-control | shared control-plane VM and kube context (local mode) |
--kustomize | ./bin/kustomize | path to the kustomize binary |
--kubectl | kubectl | kubectl binary (in onhost mode outside a pod it becomes k0s) |
--github-repo | none | owner/name for instance-request issues (or CORE_GITHUB_REPO) |
--github-label | instance-request | issue label that marks an instance request |
--console-url | none, on purpose | CORE console base URL for session-run reporting (or CORE_CONSOLE_URL / console_url) |
--image-pull-policy | none | override every imagePullPolicy the deploy applies: Always, IfNotPresent or Never (or CORE_IMAGE_PULL_POLICY) |
--with-monitoring | false | also apply the shared inference monitoring stack (needs the Prometheus Operator) |
--console-url has no default because CORE is deployed per client, each with its own console. Empty means “don’t report”: runs still record locally and core session sync delivers them later.
Command tree
Local development
| Command | What it does |
|---|---|
core dev up [face|pulse|all] | Start the dev stack (default: all) |
core dev secure [face|pulse|all] | Start the dev stack plus the single mTLS SNI gateway (unprivileged port) |
core dev down | Stop everything (backends, frontends, inference, gateway, mesh pipes) |
core dev hosts [--remove] | Map *.runink.org.local → 127.0.0.1 and grant the gateway :443 (one-time sudo) |
core dev flutter <face|pulse|core> | Hot-reload one Flutter UI against a backend. --device chrome|web-server, --endpoint, --port (defaults 5551 face / 5552 pulse / 5553 core) |
core dev frontend | Launch only the local Flutter UIs pointed at the real demo instances. --face-url, --pulse-url (or CORE_DEMO_FACE_URL / CORE_DEMO_PULSE_URL) |
core app build|flutter|generate|proto|test <name> | Per-app dev tasks: build the Go backend, build and stage the Flutter web bundle, proto + build + test, regenerate protobuf (buf), run backend tests + flutter analyze |
Cluster and deploy
| Command | What it does |
|---|---|
core cluster up|status|shell NAME|models|import VM IMG...|down|rm | Local multipass k0s lifecycle (alias clusters). models bind-mounts host GGUF dirs into the VMs; import loads images into a VM’s k0s |
core deploy platform | Provision + mesh CA + CRDs + core operator (no app instances) |
core deploy face / core deploy pulse | Deploy one app instance |
core deploy all | Platform + FACE + PULSE |
core deploy down | Tear down the overlays (local: stop VMs) |
core build ambassador | Build the shared static mTLS-proxy image |
core build operator <runink|pulse|core> | Build an operator image (+ the shared ambassador) |
core build app <face|pulse> | Build an app’s images from its sibling repo |
core build inference-activator | Build the scale-to-zero inference front-door image |
core bump-fleet-image <app> <sha> | Bump the image reference in a k0s-fleet overlay |
core mesh ca [--namespace NS] | Mint the shared mesh CA; with --namespace, distribute it as secret/core-mesh-ca |
core node dedicate --node N --app face|pulse [--tenant T] | Dedicate a node to one app (label + taint) |
core gitops install|bootstrap|render | Install Argo CD alone, apply the app-of-apps root (read the prune warning), or render every GitOps kustomization offline |
core local up|down | Install or remove the local suite (Argo, Calico, KEDA, Knative) |
core status | Show the reconciling desired state (platform + both app instances) |
core smoke | Security-surface smoke test (mesh CA + rotating-mTLS ambassador) |
core dns sync | Point endpoint hostnames at the edge IP via Namecheap (get → merge → set). --domain, --host (repeatable), --ip, --ttl (min 60), --dry-run |
core build app builds local podman images (localhost/…). It does not produce the images the box runs; those come from core-images-build.yml. See CI Workflows.Base images
core images list|mirror|preflight handles the sovereign base-image mirror. The declared set is infrastructure/images/baseimages.yaml.
| Flag (all subcommands) | Default | Meaning |
|---|---|---|
--file | infrastructure/images/baseimages.yaml | the declared base-image set |
--ipv4 | true | force IPv4 for upstream pulls |
--json | false | machine-readable output |
--only | none | restrict to these images (repeatable) |
--registry | the set’s own | destination registry override |
--timeout | 30m0s | per-request timeout |
mirror adds --dry-run and --force. preflight reports which declared images are absent from the registry at the pinned digest and exits non-zero.
Instances and access
| Command | What it does |
|---|---|
core instance request | Open a GitHub issue requesting a new instance. Flags: --app, --tenant, --namespace (default core-system), --role, --image, --replicas, --compute-units, --tag k=v, --user email[:role] (role admin|writer|reader), --variant |
core instance list [--issues] | List reconciled ClientInstances, or open requests with --issues |
core instance status | Show reconciled ClientInstances on the cluster |
core instance reconcile | Provision instance-request issues and apply user-request grants, then report back |
core instance add-user | Open an issue granting users access to an existing instance: --instance or --app/--tenant, --namespace, --user email[:role] (default role reader) |
--variant still exists and writes a variant: line into the issue’s ClientInstance YAML (internal/instance/instance.go). The ClientInstance type (operators/core/api/v1alpha1/clientinstance_types.go) no longer has a variant field, since spec.variant was removed (core#903). The flag therefore has no effect on what gets provisioned.Data connections
core connection register <manifest> registers data-source connections into CORE’s console registry from a committed manifest. Flags: --dry-run, --adopt-drift, --rotate-credentials. It authenticates with a console session from the environment only. Full guide: Connections.
Security and compliance
| Command | What it does |
|---|---|
core scan [repo...] | govulncheck across repos. --fix applies reachable-CVE bumps (go get @fixed → tidy → build-verify), --json, --repo (repeatable), --timeout (default 10m) |
core scan-sweep | scan --fix across platform repos. --owner, --repos, --branch (default security/auto-update). No workflow calls it today |
core security scan | govulncheck + gosec per Go module per root, emitting SARIF. --roots, --sarif-dir |
core security gate | Ratchet the gosec SARIF against the committed baseline; fail on new findings or new coverage holes. --baseline-dir (default .github/scripts/security-baseline), --gate-severity (default MEDIUM), --stale-days (default 90), --update |
core security report | Aggregate SARIF into docs/security-scan-report.md with the NIST SSDF mapping |
core security autoupdate | Auto-update vulnerable dependencies |
core compliance gate | Deterministic control checks over a repo; non-zero exit on findings. --repo, --changed-files, --format text|md|json, --summary |
core compliance inventory | Recompute the audit-emitter inventory (--write updates the policy) |
Coding agent
| Command | What it does |
|---|---|
core auth login|logout|status | GitHub Device Flow sign-in. login takes --force and --no-browser |
core session start | Start a new coding session |
core session resume <id> | Resume a persisted session with a new instruction |
core session list | List persisted sessions |
core session serve | Run queued session instructions from the CORE console on this machine |
core session sync | Re-send pending session reports to the console |
The session flags are covered in Coding Sessions.
Install medium, wizard and Marketplace
| Command | What it does |
|---|---|
core guide-bundle build|sign BUNDLE|verify BUNDLE [SIG]|keygen|source | Build and sign CORE’s install guide (docs/install-guide) as a private river-guide bundle |
core wizard | Install Runink applications on a River node (and configure a DEMO instance). --serve runs the graphical wizard on a loopback-only page opened with a one-time link; --answers runs scripted |
core wizard status|skip|demo remove | Show what was installed; remove the first-boot login hint; remove the DEMO instance and revoke every demo password |
core marketplace ready | Exit 0 once every app of the golden answers file is installed, healthy and answering through the edge |
core marketplace admin-credentials show|deliver | Print the production admin logins over SSH, or write them as a new Secret Manager version |
core marketplace secret-access | Read the Secret Manager secret an instance attribute names into a 0600 file on tmpfs |
Selected core wizard flags: --apps (from face,pulse,luna,forge; core is implied), --role server|runner, --offline, --online, --payloads, --passphrase-file, --state (default /etc/runink/wizard-state.json), --dry-run (runs against an in-memory fake node), --listen (loopback only; non-loopback is refused), --firstboot, --installation-admin, --no-demo. The installer guide is docs/install-guide/50-wizard.md.
Command-name quick index
app · auth · build · bump-fleet-image · cluster · completion · compliance · connection · deploy · dev · dns · gitops · guide-bundle · images · instance · local · marketplace · mesh · node · scan · scan-sweep · security · session · smoke · status · wizard