Configuration Commands

Kānuka provides configuration commands for managing user and project settings, including device names and user information. To understand how configuration works at a deeper level, see the configuration concepts page.

First-Time Setup

When you first use Kānuka, you need to set up your user identity. This is done automatically when you run kanuka secrets init, but you can also do it explicitly:

kanuka config init

This will prompt you for:

• Email address (required) - Your identifier across all projects.
• Display name (optional) - For audit log features.
• Default device name - Defaults to your computer’s hostname.

For non-interactive setup (useful in CI/CD or scripts):

kanuka config init --email [email protected] --device my-laptop

Viewing Your Configuration

To see your current user configuration:

kanuka config show

Example output:

User Configuration (~/.config/kanuka/config.toml):
  Email:          [email protected]
  Name:           Alice Smith
  User ID:        6ba7b810-9dad-11d1-80b4-00c04fd430c8
  Default Device: MacBook-Pro

Projects:
  550e8400... -> workstation (my-awesome-project)

To see the project configuration (must be in a project directory):

kanuka config show --project

For JSON output (useful for scripts):

kanuka config show --json
kanuka config show --project --json

Configuration Commands

Init

Set up your user identity:

# Interactive setup
kanuka config init

# Non-interactive setup
kanuka config init --email [email protected] --name "Alice Smith" --device workstation

Show

View your configuration:

# Show user configuration
kanuka config show

# Show project configuration
kanuka config show --project

# Show as JSON
kanuka config show --json
kanuka config show --project --json

List Devices

List all devices in the project:

# List all devices
kanuka config list-devices

# Filter by user
kanuka config list-devices --user [email protected]

Set Default Device

Set your default device name:

kanuka config set-default-device my-laptop

Set Project Device

Set your device name for a specific project:

# From within the project directory
kanuka config set-project-device work-laptop

# From anywhere, by project UUID
kanuka config set-project-device --project-uuid 550e8400-e29b-41d4-a716-446655440000 workstation

Listing Devices

To see all devices registered in the current project:

kanuka config list-devices

This displays all users and their devices, including device names, UUIDs, and creation dates.

Example output:

Devices in project 'my-awesome-project':

[email protected] (6ba7b810...)
  - workstation (created: Jan 6, 2025)
  - laptop (created: Jan 7, 2025)

[email protected] (8ba7b810...)
  - macbook (created: Jan 5, 2025)

To filter by a specific user:

kanuka config list-devices --user [email protected]

Setting Your Device Name

There are two types of device name settings:

Default Device Name

Set your default device name for new projects. This is used when you initialize or register for a project for the first time.

kanuka config set-default-device my-laptop

Project Device Name

Set your device name for an existing project. This updates both your user configuration and the project configuration to keep them in sync.

kanuka config set-project-device my-laptop

To set a device name for a specific project by UUID (without being in the project directory):

kanuka config set-project-device --project-uuid 550e8400-e29b-41d4-a716-446655440000 workstation

Device Name Requirements

Device names must:

• Start with an alphanumeric character
• Contain only alphanumeric characters, hyphens, and underscores
• Be unique per user within a project

Common Workflows

Adding a New Device

When you want to access a project from a new computer:

1. Clone the repository on your new device.
2. Run kanuka config init to set up your identity (use the same email).
3. Set a unique device name for this project:

   kanuka config set-project-device work-laptop

4. Run kanuka secrets create to generate keys for this device.
5. Ask a teammate to register your new device:

   kanuka secrets register --user [email protected]

6. Pull the latest changes and decrypt:

   git pull && kanuka secrets decrypt

Checking Who Has Access

To see all users and devices with access to the project:

kanuka config list-devices

Or view the full project configuration:

kanuka config show --project

Cleaning Up Old Devices

If you no longer use a device, you should revoke its access:

kanuka secrets revoke --user [email protected] --device old-laptop

See the revoke guide for more details.

Next Steps

• Learn about creating keys for a new device
• Learn about revoking access for compromised devices
• Understand the configuration concepts
• See the command reference for all available options