Binary not shipped yet
The split repos do not currently include a canonical kf package with a bin entry.
Ask about previewCLI
kf CLI protocol preview.
The split repos do not ship a canonical kf binary yet. This page tracks the planned terminal workflow and the executable CLI protocol proof that already exercises device auth, token minting, command receipts, and source-channel stamping through the same policy boundary as GraphQL and MCP.
Preview status
Use protocol proof until the binary lands.
Current split proof covers the CLI auth and command protocol, not a published executable. Preview installers, checksums, and package version claims become valid only after a canonical split-owned binary is released.
Review protocol workflows
The current executable proof covers device auth, token minting, command receipts, and source-channel stamping.
Open CLI referenceKeep secrets out of argv
Prefer KF_CLI_API_KEY, --api-key-stdin, or OAuth device login. Endpoint URLs with embedded credentials are rejected.
See controlsSetup
Planned setup flow for the shipped binary.
These steps are the site-native version of the CLI onboarding path. Treat them as protocol examples until the `kf` package is present in a canonical repo with a package `bin` entry and release proof.
1. Wait for the preview bundle
# Planned after the canonical kf package ships. kf version --pretty
2. Confirm the shipped binary
kf version --pretty kf commands list --pretty
3. Create a profile
printf '%s' "$KF_CLI_API_KEY" | \ kf login \ --endpoint https://api.example.com/graphql \ --tenant tenant-acme \ --environment sandbox \ --api-key-stdin
4. Check the resolved auth source
kf auth status --pretty kf profile show --pretty kf profile list --pretty
5. Use OAuth for human operators
kf login --oauth \ --endpoint https://api.example.com/graphql \ --tenant tenant-acme \ --environment sandbox kf logout --profile default
Workflows
The common end-to-end paths.
Every command emits JSON. Pass --pretty for humans, leave it off for scripts, and use command ids to move between events, receipts, and trace output.
Inspect what the platform can do
Start with registry and reference reads before touching tenant state.
kf commands list --pretty kf commands show CreateReservation --pretty kf version --pretty
Read operational state
Inventory, events, receipts, feed, Control Center, and flow trace all go through authenticated GraphQL.
kf inventory levels --tenant tenant-acme --environment sandbox --limit 20 --pretty kf events list --tenant tenant-acme --environment sandbox --limit 20 --pretty kf receipts list --tenant tenant-acme --environment sandbox --limit 20 --pretty kf control-center snapshot --tenant tenant-acme --environment sandbox --limit 25 --pretty
Follow a receipt chain
Use command ids, order ids, reservation ids, or correlation ids to move from a symptom to the exact write.
kf receipts show cmd_01HZ7GCK6MN1Q9V8P3T7B5XJ4F --tenant tenant-acme --pretty kf trace flow --tenant tenant-acme --order-id order_123 --limit 50 --pretty
Run selected writes
Current writes are explicit command-backed paths. They return receipts and honor policy, scopes, expected versions, and idempotency.
kf reservation commit \ --tenant tenant-acme \ --reservation-id rsv_123 \ --expected-version 4 \ --actor-type USER \ --actor-id usr_123 \ --pretty kf feed send \ --tenant tenant-acme \ --title "Ops alert" \ --body "Cycle count is ready." \ --actor-type USER \ --actor-id usr_123 \ --category ALERT \ --pretty
Create preview starter files
The bootstrap helper writes starter files for a preview integration workspace. It does not create tenants or write domain tables.
kf bootstrap template --tenant tenant-acme --environment sandbox --pretty kf bootstrap init --dir .local/bootstrap/acme --tenant tenant-acme --environment sandbox
Auth and routing
Resolution rules are explicit.
Tenant resolution order is --tenant, KF_CLI_TENANT_ID, then the active profile.
Environment resolution order is --environment, KF_CLI_ENVIRONMENT_ID, then profile default, then sandbox.
API key resolution order is flag, stdin, then environment. The profile stores only a redacted preview from login, never a reusable API key.
Non-local GraphQL endpoints must use HTTPS, and endpoint URLs cannot contain usernames or passwords.
Troubleshooting
Fast checks before opening a ticket.
Profile not found
Run kf profile list --pretty, then pass --profile <name> or set the active profile with kf profile use <name>.
No auth source
Run kf auth status --pretty. For API keys, export KF_CLI_API_KEY or pipe the key through --api-key-stdin.
GraphQL endpoint rejected
Use the HTTPS endpoint issued with your preview workspace. Ask KarmanFlow support before routing the CLI through a custom domain.
Write command rejected
Check the required scope, actor fields, expectedVersion, and idempotency key. High-risk commands still flow through approval policy.
Reference
Hosted command reference.
The reference lists every preview topic, action, required flag, optional flag, and example available to operators and builders.
Ready
Bring a tenant, endpoint, and one real workflow.
The fastest developer session starts with one command you need to inspect or one write you need to prove. The CLI, GraphQL, MCP, and receipts all meet at the same command boundary.