This tutorial walks you through daily Kizuna workflows using the kz CLI and its built-in terminal user interface (TUI).

Prerequisites

• The Kizuna CLI installed (see CLI Overview)
• A running Kizuna instance
• An account on that instance

Step 1: Initial Setup

Initialize Configuration

kz config init

This creates the configuration directory and a default config file. Check where files were created:

kz config path

Config:      ~/.config/kizuna/config.toml
Credentials: ~/.config/kizuna/credentials.toml
Cache:       ~/.cache/kizuna/
Data:        ~/.local/share/kizuna/

Authenticate

kz auth login

This opens your browser for OAuth authentication. After approving, the CLI stores your token.

Verify the connection:

kz auth status

Profile:  default
Instance: https://kizuna.yourcompany.com
User:     alice
Status:   Authenticated
Expires:  2026-04-25T10:00:00Z

Step 2: Configure Multiple Profiles

If you work with multiple Kizuna instances (e.g., work and personal):

Edit the Configuration

kz config edit

Add profiles:

default_profile = "work"

[profiles.work]
name = "work"
instance_url = "https://kizuna.yourcompany.com"
default_org = "acme-corp"

[profiles.personal]
name = "personal"
instance_url = "https://cloud.kizuna.codes"
default_org = "my-projects"

[api]
timeout = 30
retry = true

[ui]
color = "auto"
format = "table"

Authenticate Each Profile

kz --profile work auth login
kz --profile personal auth login

Switch Between Profiles

kz auth switch personal
kz auth status   # Confirms "personal" profile is active

Step 3: Policy Gateway Operations

The policy gateway is one of the CLI's most powerful features — use it for CI/CD gates and security automation.

Check Permissions

Before performing sensitive operations, verify they're allowed:

# Can I delete this repository?
kz policy check --action "repo.delete" --resource "acme-corp/legacy-api"

Action:   repo.delete
Resource: acme-corp/legacy-api
Result:   DENIED
Reason:   Repository has active branches and open PRs

Check with Context

Provide additional context for nuanced policy evaluation:

kz policy check \
  --action "deploy.production" \
  --resource "acme-corp/api-service" \
  --context '{"branch": "main", "user_role": "lead", "ci_passed": true}'

Action:   deploy.production
Resource: acme-corp/api-service
Result:   ALLOWED

Use in CI/CD Scripts

#!/bin/bash
# deployment-gate.sh

# Check policy before deploying
if kz policy check \
  --action "deploy.production" \
  --resource "$REPO" \
  --context "{\"branch\": \"$BRANCH\", \"ci_passed\": $CI_PASSED}" \
  --quiet; then

  echo "Policy check passed — deploying"
  ./deploy.sh
else
  echo "Policy check failed — deployment blocked"
  exit 1
fi

Invoke Tools Through Policy Gateway

Execute platform tools with full audit logging:

# Trigger a code review
kz policy invoke \
  --tool "code-review" \
  --input '{"repo": "acme-corp/api-service", "pr": 42}'

Tool:     code-review
Status:   Success
Duration: 12.3s
Audit ID: aud_abc123
Result:   Review completed — 2 issues found

Long-Running Operations

For operations that take time, use async mode:

kz policy invoke \
  --tool "security-scan" \
  --input '{"repo": "acme-corp/api-service", "branch": "main"}' \
  --async \
  --timeout 300

Tool:     security-scan
Status:   Accepted (async)
Audit ID: aud_def456

Step 4: OIDC Client Management

Manage OAuth clients for agent and service integrations:

List Existing Clients

kz identity client list

ID                                    Name                  Grant Types
────────────────────────────────────  ────────────────────  ─────────────────────
550e8400-e29b-41d4-a716-44665544000  ci-integration        client_credentials
6ba7b810-9dad-11d1-80b4-00c04fd430c8 web-app               authorization_code

Create a New Client

kz identity client create \
  --name "monitoring-service" \
  --redirect-uri "https://monitoring.acme.com/callback" \
  --grant-types "client_credentials"

Client Created:
  ID:     7c9e6679-7425-40de-944b-e07fc1f90ae7
  Name:   monitoring-service
  Secret: kz_sec_xxxxxxxxxxxxxxxxxxxxxxxx   ← Save this now!

Important: The client secret is displayed only once. Store it in your secrets manager.

Rotate a Client Secret

When a secret is compromised or per your rotation policy:

kz identity client rotate-secret 7c9e6679-7425-40de-944b-e07fc1f90ae7

New Secret: kz_sec_yyyyyyyyyyyyyyyyyyyyyyyy   ← Update your services!

Delete a Client

kz identity client delete 7c9e6679-...

The CLI prompts for confirmation. Use --force to skip:

kz identity client delete 7c9e6679-... --force

Step 5: Using the TUI

Launch the full terminal interface:

kz tui

Navigate the Interface

1. Sidebar — Use j/k (or arrow keys) to select a view
2. Enter — Open the selected view
3. Main panel — Browse content with vim-style navigation

Quick Actions

What You Want to Do	Keys
Search repos/issues/PRs	/ then type query
Open a file	Navigate to it, press o
View blame	Select a file, press b
Move an issue on Kanban	Select it, press m
Approve a PR	Open it, press a
Merge a PR	Open it, press m
Refresh data	Press r
Get help	Press ?
Go back	Press Backspace
Quit	Press q

Example: Review a PR in the TUI

1. Launch: kz tui
2. Navigate to PRs in the sidebar
3. Press Enter to open the PR list
4. Use j/k to find the PR
5. Press Enter to open it
6. Review the diff
7. Press a to approve, or c to comment, or R to request changes

Step 6: JSON Output for Scripting

Every command supports --json for machine-readable output:

# Get policy check result as JSON
kz policy check \
  --action "agent.create" \
  --resource "acme-corp" \
  --format json

{
  "action": "agent.create",
  "resource": "acme-corp",
  "result": "allowed",
  "context": {},
  "evaluated_at": "2026-03-26T10:00:00Z"
}

Combine with jq for scripting:

# Extract just the result
kz policy check --action "deploy.production" --resource "acme/api" --format json \
  | jq -r '.result'

Step 7: Offline Mode

Work with cached data when you don't have connectivity:

# Launch TUI with cached data
kz --offline tui

# Check cached policy results
kz --offline policy check --action "repo.read" --resource "acme/api"

Daily Workflow Summary

# Morning: check auth and switch to work profile
kz auth status
kz auth switch work

# Check what you can deploy
kz policy check --action "deploy.staging" --resource "acme/api"

# Launch TUI to browse issues and PRs
kz tui

# In CI/CD: gate deployment with policy check
kz policy check --action "deploy.production" --resource "acme/api" --quiet && deploy.sh

# Rotate a client secret on schedule
kz identity client rotate-secret $CLIENT_ID

Next Steps

• CLI Commands Reference — All commands in detail
• CLI Configuration — Profiles and environment variables
• TUI Guide — Complete TUI documentation
• Tutorial: Onboarding — New user walkthrough