Command Reference

This page provides a comprehensive reference for all Kānuka commands and their options.

Secrets Management Commands

`kanuka`

Usage:
  kanuka [flags]
  kanuka [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Manage user and project configuration
  help        Help about any command
  secrets     Manage secrets stored in the repository

Flags:
  -h, --help   help for kanuka

Completion

Generate autocompletion scripts for various shells.

`kanuka completion`

Usage:
  kanuka completion [command]

Available Commands:
  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

Flags:
  -h, --help   help for completion

Secrets Management

Provides encryption, decryption, registration, revocation, and initialization of secrets.

`kanuka secrets`

Usage:
  kanuka secrets [command]

  Available Commands:
  access      List users with access to the project's secrets
  clean       Remove orphaned keys and inconsistent state
  create      Creates and adds your public key, and gives instructions on how to gain access
  decrypt     Decrypts the .env.kanuka file back into .env using your Kānuka key
  doctor      Run health checks on the project
  encrypt     Encrypts the .env file into .env.kanuka using your Kānuka key
  export      Create a backup archive of encrypted secrets
  import      Restore secrets from a backup archive
  init        Initializes the secrets store
  log         View the audit log of operations
  register    Registers a new user to be given access to the repository's secrets
  revoke      Revokes access to the secret store
  rotate      Rotate your personal keypair
  status      Show encryption status of secret files
  sync        Re-encrypt all secrets with a new symmetric key

Flags:
  -h, --help   help for secrets

`kanuka secrets create`

Creates and adds your public key, and gives instructions on how to gain access.

Usage:
  kanuka secrets create [flags]

Flags:
  -f, --force     force key creation
  -h, --help      help for create
  -v, --verbose   enable verbose output

`kanuka secrets decrypt`

Decrypts the .env.kanuka file back into .env using your Kānuka key.

Usage:
  kanuka secrets decrypt [files...] [flags]

Flags:
      --dry-run             preview decryption without making changes
  -h, --help                help for decrypt
      --private-key-stdin   read private key from stdin
  -v, --verbose             enable verbose output

Arguments:

If no files are specified, all .kanuka files are decrypted. You can specify:

Individual files: .env.kanuka, .env.local.kanuka
Glob patterns: "services/*/.env.kanuka", "**/.env.production.kanuka"
Directories: services/api/ (decrypts all .kanuka files within)

Examples:

# Preview which files would be decrypted
kanuka secrets decrypt --dry-run

# Decrypt all .kanuka files
kanuka secrets decrypt

# Decrypt specific files
kanuka secrets decrypt .env.kanuka .env.local.kanuka

# Decrypt using glob pattern
kanuka secrets decrypt "services/*/.env.kanuka"

# Decrypt all .kanuka files in a directory
kanuka secrets decrypt services/api/

`kanuka secrets encrypt`

Encrypts the .env file into .env.kanuka using your Kānuka key.

Usage:
  kanuka secrets encrypt [files...] [flags]

Flags:
      --dry-run             preview encryption without making changes
  -h, --help                help for encrypt
      --private-key-stdin   read private key from stdin
  -v, --verbose             enable verbose output

Arguments:

If no files are specified, all .env files are encrypted. You can specify:

Individual files: .env, .env.local
Glob patterns: "services/*/.env", "**/.env.production"
Directories: services/api/ (encrypts all .env files within)

Examples:

# Preview which files would be encrypted
kanuka secrets encrypt --dry-run

# Encrypt all .env files
kanuka secrets encrypt

# Encrypt specific files
kanuka secrets encrypt .env .env.local

# Encrypt using glob pattern
kanuka secrets encrypt "services/*/.env"

# Encrypt all .env files in a directory
kanuka secrets encrypt services/api/

`kanuka secrets init`

Initializes the secrets store.

Usage:
  kanuka secrets init [flags]

Flags:
  -h, --help      help for init
  -n, --name      project name (defaults to directory name)
  -v, --verbose   enable verbose output
  -y, --yes       non-interactive mode

`kanuka secrets log`

Displays the audit log of secrets operations.

Usage:
  kanuka secrets log [flags]

Flags:
  -h, --help              help for log
      --json              output as JSON array
  -n, --number int        limit number of entries shown
      --oneline           compact one-line format
      --operation string  filter by operation type (comma-separated)
      --reverse           show most recent entries first
      --since string      show entries after date (YYYY-MM-DD)
      --until string      show entries before date (YYYY-MM-DD)
      --user string       filter by user email
  -v, --verbose           enable verbose output

Examples:

# View full log
kanuka secrets log

# Last 10 entries, most recent first
kanuka secrets log -n 10 --reverse

# Filter by user
kanuka secrets log --user [email protected]

# Filter by operation type
kanuka secrets log --operation encrypt,decrypt

# Filter by date range
kanuka secrets log --since 2024-01-01 --until 2024-01-31

# Compact one-line format
kanuka secrets log --oneline

# JSON output for scripting
kanuka secrets log --json

`kanuka secrets register`

Registers a new user to be given access to the repository’s secrets.

Usage:
  kanuka secrets register [flags]

Flags:
      --dry-run                  preview registration without making changes
  -f, --file string              the path to a custom public key — will add public key to the project
      --force                    skip confirmation when updating existing user
  -h, --help                     help for register
      --private-key-stdin        read private key from stdin
      --pubkey string            OpenSSH or PEM public key content to be saved with the specified username
  -u, --user string              username to register for access
  -v, --verbose                  enable verbose output

Examples:

# Preview what would be created
kanuka secrets register --user [email protected] --dry-run

# Register a user by email
kanuka secrets register --user [email protected]

# Re-register existing user (skip confirmation)
kanuka secrets register --user [email protected] --force

# Register using a public key file
kanuka secrets register --file path/to/key.pub

`kanuka secrets revoke`

Revokes access to the secret store.

Usage:
  kanuka secrets revoke [flags]

Flags:
  -d, --device string   revoke a specific device only
      --dry-run         preview revocation without making changes
  -f, --file string     path to the .kanuka file to revoke
  -h, --help            help for revoke
  -u, --user string     user email to revoke
  -v, --verbose         enable verbose output
  -y, --yes             skip confirmation prompts

Examples:

# Preview what would be revoked
kanuka secrets revoke --user [email protected] --dry-run

# Revoke all devices for a user
kanuka secrets revoke --user [email protected]

# Revoke a specific device
kanuka secrets revoke --user [email protected] --device old-laptop --dry-run

# Revoke by file path
kanuka secrets revoke --file .kanuka/secrets/uuid.kanuka

`kanuka secrets sync`

Re-encrypts all secrets with a newly generated symmetric key.

Usage:
  kanuka secrets sync [flags]

Flags:
      --dry-run             preview sync without making changes
  -h, --help                help for sync
      --private-key-stdin   read private key from stdin
  -v, --verbose             enable verbose output

Examples:

# Preview what would happen
kanuka secrets sync --dry-run

# Rotate encryption key and re-encrypt all secrets
kanuka secrets sync

# Use in CI/CD with piped private key
echo "$KANUKA_PRIVATE_KEY" | kanuka secrets sync --private-key-stdin

`kanuka secrets rotate`

Rotates your personal keypair, generating a new RSA key pair and updating your access.

Usage:
  kanuka secrets rotate [flags]

Flags:
      --force               skip confirmation prompt
  -h, --help                help for rotate
      --private-key-stdin   read private key from stdin
  -v, --verbose             enable verbose output

Examples:

# Rotate keypair with confirmation
kanuka secrets rotate

# Rotate keypair without confirmation
kanuka secrets rotate --force

`kanuka secrets access`

Lists all users who have access to the project’s secrets.

Usage:
  kanuka secrets access [flags]

Flags:
  -h, --help      help for access
      --json      output in JSON format
  -v, --verbose   enable verbose output

Examples:

# View all users with access
kanuka secrets access

# JSON output for scripting
kanuka secrets access --json

`kanuka secrets status`

Shows the encryption status of all secret files in the project.

Usage:
  kanuka secrets status [flags]

Flags:
  -h, --help      help for status
      --json      output in JSON format
  -v, --verbose   enable verbose output

Examples:

# View status of all secret files
kanuka secrets status

# JSON output for scripting
kanuka secrets status --json

`kanuka secrets clean`

Removes orphaned keys and inconsistent state.

Usage:
  kanuka secrets clean [flags]

Flags:
      --dry-run     preview cleanup without making changes
      --force       skip confirmation prompt
  -h, --help        help for clean
  -v, --verbose     enable verbose output

Examples:

# Preview what would be cleaned
kanuka secrets clean --dry-run

# Clean with confirmation
kanuka secrets clean

# Clean without confirmation
kanuka secrets clean --force

`kanuka secrets doctor`

Runs health checks on the project and provides actionable suggestions.

Usage:
  kanuka secrets doctor [flags]

Flags:
  -h, --help      help for doctor
      --json      output in JSON format
  -v, --verbose   enable verbose output

Examples:

# Run all health checks
kanuka secrets doctor

# JSON output for CI/CD
kanuka secrets doctor --json

Exit codes:

0 - All checks passed
1 - Warnings found
2 - Errors found

`kanuka secrets export`

Creates a backup archive of encrypted secrets.

Usage:
  kanuka secrets export [flags]

Flags:
  -h, --help            help for export
  -o, --output string   output file path (default: kanuka-secrets-YYYY-MM-DD.tar.gz)
  -v, --verbose         enable verbose output

Examples:

# Export with default filename
kanuka secrets export

# Export to custom path
kanuka secrets export -o /backups/project-secrets.tar.gz

`kanuka secrets import`

Restores secrets from a backup archive.

Usage:
  kanuka secrets import [archive] [flags]

Flags:
      --dry-run     preview import without making changes
  -h, --help        help for import
      --merge       add new files, keep existing
      --replace     delete existing, use backup
  -v, --verbose     enable verbose output

Examples:

# Import with interactive prompt
kanuka secrets import backup.tar.gz

# Merge new files, keep existing
kanuka secrets import backup.tar.gz --merge

# Replace all with backup
kanuka secrets import backup.tar.gz --replace

# Preview import
kanuka secrets import backup.tar.gz --dry-run

Configuration Management

Provides commands for managing user and project configuration settings.

`kanuka config`

Usage:
  kanuka config [command]

Available Commands:
  init                Initialize your user configuration
  list-devices        List all devices in project
  set-default-device   Set your default device name for new projects
  set-project-device   Set your device name for a project
  show                Display current configuration

Flags:
  -d, --debug     enable debug output
  -h, --help      help for config
  -v, --verbose   enable verbose output

`kanuka config init`

Sets up your Kānuka user identity. Creates or updates your user configuration file at ~/.config/kanuka/config.toml.

Usage:
  kanuka config init [flags]

Flags:
      --device string   default device name (defaults to hostname)
  -e, --email string    your email address
  -h, --help            help for init
  -n, --name string     your display name (optional)

Global Flags:
  -d, --debug     enable debug output
  -v, --verbose   enable verbose output

Examples:

# Interactive setup
kanuka config init

# Non-interactive setup
kanuka config init --email [email protected] --device macbook

# With all options
kanuka config init --email [email protected] --name "Alice Smith" --device workstation

`kanuka config show`

Displays the current Kānuka configuration. By default, shows user configuration. Use --project to show project configuration.

Usage:
  kanuka config show [flags]

Flags:
  -h, --help      help for show
      --json      output in JSON format
  -p, --project   show project configuration instead of user configuration

Global Flags:
  -d, --debug     enable debug output
  -v, --verbose   enable verbose output

Examples:

# Show user configuration
kanuka config show

# Show project configuration (must be in a project directory)
kanuka config show --project

# Output in JSON format
kanuka config show --json

`kanuka config set-default-device`

Sets your default device name in your user configuration. This default name is used when you initialize or register for new projects.

Usage:
  kanuka config set-default-device [device-name]

Flags:
  -h, --help          help for set-default-device

Global Flags:
  -d, --debug     enable debug output
  -v, --verbose   enable verbose output

Examples:

# Set your default device name
kanuka config set-default-device my-laptop

`kanuka config set-project-device`

Sets your device name for an existing project in both user and project configuration. This is the command to use when you want to change your device name for a project you’re already part of.

Usage:
  kanuka config set-project-device [device-name] [flags]

Flags:
  -h, --help                  help for set-project-device
      --project-uuid string   project UUID (defaults to current project)

Global Flags:
  -d, --debug     enable debug output
  -v, --verbose   enable verbose output

Examples:

# Set device name for the current project
kanuka config set-project-device my-laptop

# Set device name for a specific project
kanuka config set-project-device --project-uuid 550e8400-e29b-41d4-a716-446655440000 workstation

`kanuka config list-devices`

Lists all devices registered in the project configuration.

Usage:
  kanuka config list-devices [flags]

Flags:
  -h, --help          help for list-devices
  -u, --user string   filter by user email

Global Flags:
  -d, --debug     enable debug output
  -v, --verbose   enable verbose output

Examples:

# List all devices in the project
kanuka config list-devices

# List devices for a specific user
kanuka config list-devices --user [email protected]

Shell Completion Setup

Use kanuka completion [shell] to generate completion scripts for your preferred shell:

Bash: kanuka completion bash
Zsh: kanuka completion zsh
Fish: kanuka completion fish
PowerShell: kanuka completion powershell

Refer to each sub-command’s help for details on how to use the generated script.