Documentation/Configuration

Configuration Guide

Customize RealmKit CLI behavior with configuration files, environment variables, and command-line options. Set up defaults that work for your workflow.

Quick Setup

Get started with basic configuration in under a minute

1. Set Your API Key

realmkit config set apiKey your-api-key-here

2. Configure Defaults

realmkit config set defaultCategory saas
realmkit config set authorName "Your Name"
realmkit config set authorEmail "you@example.com"

3. Verify Configuration

realmkit config list

Configuration Files

Global Configuration
High

~/.realmkit/config.jsonUser-wide settings that apply to all RealmKit operations

Example Configuration

{
  "registry": "https://registry.realmkit.com",
  "apiKey": "rk_live_...",
  "defaultCategory": "web",
  "autoInstall": true,
  "git": {
    "autoInit": true,
    "defaultBranch": "main"
  },
  "templates": {
    "defaultLicense": "MIT",
    "authorName": "Your Name",
    "authorEmail": "you@example.com"
  }
}

Project Configuration
Medium

./.realmkit.jsonProject-specific settings that override global configuration

Example Configuration

{
  "name": "my-custom-realm",
  "version": "1.0.0",
  "category": "saas",
  "features": {
    "auth": true,
    "payments": false,
    "database": true
  },
  "scripts": {
    "setup": "npm install && npm run db:setup",
    "dev": "npm run dev"
  }
}

Environment Variables
High

.env / shell environmentEnvironment-based configuration for sensitive data

Example Configuration

{
  "REALMKIT_API_KEY": "your-api-key-here",
  "REALMKIT_REGISTRY": "https://registry.realmkit.com",
  "REALMKIT_DEBUG": "true",
  "REALMKIT_TIMEOUT": "30000",
  "REALMKIT_USER_AGENT": "MyApp/1.0"
}

Configuration Options

Complete reference of all available configuration options

Authentication

apiKey

string

null

Your RealmKit API key for authenticated requests

registry

string

https://registry.realmkit.com

RealmKit registry URL

userAgent

string

RealmKit CLI/version

Custom user agent for API requests

Project Defaults

defaultCategory

string

web

Default category for new realms

defaultLicense

string

MIT

Default license for new realms

autoInstall

boolean

true

Automatically install dependencies after realm creation

authorName

string

git config user.name

Default author name for realm metadata

authorEmail

string

git config user.email

Default author email for realm metadata

Git Integration

git.autoInit

boolean

true

Automatically initialize git repository

git.defaultBranch

string

main

Default branch name for new repositories

git.autoCommit

boolean

false

Create initial commit after realm creation

git.commitMessage

string

Initial commit from RealmKit

Default initial commit message

Performance

timeout

number

30000

Request timeout in milliseconds

retries

number

3

Number of retry attempts for failed requests

concurrency

number

5

Maximum concurrent operations

cacheDir

string

~/.realmkit/cache

Directory for caching downloaded realms

Debug & Logging

debug

boolean

false

Enable debug logging

logLevel

string

info

Log level (error, warn, info, debug)

logFile

string

null

Path to log file

verbose

boolean

false

Enable verbose output

Environment Variables

Override configuration using environment variables

Priority Order

Environment variables take precedence over configuration files. The order is: CLI flags → Environment variables → Project config → Global config → Defaults

REALMKIT_API_KEY

API key for authentication

REALMKIT_REGISTRY

Registry URL override

REALMKIT_DEBUG

Enable debug mode (true/false)

REALMKIT_TIMEOUT

Request timeout in milliseconds

REALMKIT_CONFIG_PATH

Custom config file path

REALMKIT_CACHE_DIR

Custom cache directory

REALMKIT_NO_COLOR

Disable colored output (true/false)

REALMKIT_USER_AGENT

Custom user agent string

Example Usage

# Set API key via environment
export REALMKIT_API_KEY="your-api-key-here"

# Enable debug mode
export REALMKIT_DEBUG=true

# Use custom registry
export REALMKIT_REGISTRY="https://your-registry.com"

# Run RealmKit with environment config
realmkit list

CLI Configuration Commands

Manage configuration using the command line interface

realmkit config list

Show all current configuration values

realmkit config list

realmkit config get <key>

Get a specific configuration value

realmkit config get apiKey

realmkit config set <key> <value>

Set a configuration value

realmkit config set defaultCategory saas

realmkit config unset <key>

Remove a configuration value

realmkit config unset apiKey

realmkit config reset

Reset configuration to defaults

realmkit config reset --confirm

realmkit config edit

Open configuration file in editor

realmkit config edit --global

Configuration Best Practices

Tips for maintaining secure and maintainable configuration

✓ Recommended

Store API keys in environment variables
Use project-specific config for team settings
Set sensible defaults in global config
Version control project config files
Document custom configuration choices

✗ Avoid

Hardcoding API keys in config files
Committing sensitive data to version control
Using overly permissive timeouts
Ignoring configuration validation errors
Setting extremely high concurrency limits

Troubleshooting Configuration

Common configuration issues and their solutions

Configuration Not Loading

• Check file permissions on config files

• Verify JSON syntax with realmkit config validate

• Ensure config file paths are correct

• Check for typos in environment variable names

API Key Issues

• Verify key format starts with rk_live_ or rk_test_

• Check key hasn't been revoked in account settings

• Ensure key has required scopes for operations

• Test key with realmkit auth test

Debug Configuration Issues

# Enable debug mode
realmkit config set debug true

# Show all configuration sources
realmkit config list --verbose

# Test configuration
realmkit config validate