kumiho-cli

Command-line tools for Kumiho Cloud asset management system.

Overview

kumiho-cli provides command-line utilities for authenticating with Kumiho Cloud and managing credentials. It's used by all Kumiho SDKs (Python, C++, Dart, FastAPI) to provide a unified authentication experience.

Installation

pip install kumiho-cli

Or install with pipx (recommended for CLI tools):

pipx install kumiho-cli

Quick Start

Login

Authenticate with your Kumiho Cloud credentials:

kumiho-cli login

This will:

1. Prompt for your Kumiho Cloud email and password
2. Obtain authentication tokens from Firebase
3. Exchange for a Control Plane JWT
4. Store credentials securely in ~/.kumiho/kumiho_authentication.json

Refresh Token

Refresh your authentication token:

kumiho-cli refresh

Check Status

View your current authentication status:

kumiho-cli whoami

Credential Storage

Credentials are stored in:

• Location: ~/.kumiho/kumiho_authentication.json
• Permissions: 0600 (read/write for owner only)
• Format: JSON with Firebase ID token, refresh token, and Control Plane JWT

Environment Variables

Variable	Description	Default
KUMIHO_CONFIG_DIR	Override config directory	~/.kumiho
KUMIHO_FIREBASE_API_KEY	Firebase API key	(built-in)
KUMIHO_FIREBASE_PROJECT_ID	Firebase project ID	(optional)
KUMIHO_CONTROL_PLANE_API_URL	Control plane URL	https://kumiho.io
KUMIHO_AUTH_TOKEN_GRACE_SECONDS	Token refresh grace period	300

Usage with SDKs

Python SDK

# Install kumiho with CLI tools
pip install kumiho[cli]

# Or install separately
pip install kumiho kumiho-cli

import kumiho

# Automatically uses credentials from kumiho-cli
kumiho.auto_configure_from_discovery()
projects = kumiho.get_projects()

C++ SDK

# One-time setup
pip install kumiho-cli
kumiho-cli login

#include <kumiho/kumiho.hpp>

// Automatically loads tokens from ~/.kumiho/
auto client = kumiho::Client::createFromEnv();

Commands

login

Interactive login with email and password.

kumiho-cli login [--api-key KEY] [--project-id ID]

Options:

• --api-key: Override Firebase API key (default: uses built-in key)
• --project-id: Specify Firebase project ID (optional)

refresh

Refresh the cached authentication token.

kumiho-cli refresh

whoami

Display current user information.

kumiho-cli whoami

Security Best Practices

1. Never commit credentials: Add ~/.kumiho/ to your .gitignore
2. Use environment variables in CI/CD: Set KUMIHO_AUTH_TOKEN instead of storing files
3. Rotate tokens regularly: Use kumiho-cli refresh to get fresh tokens
4. Protect credential files: The CLI automatically sets 0600 permissions

CI/CD Integration

For automated environments (GitHub Actions, Jenkins, etc.):

# Option 1: Use environment variable
export KUMIHO_AUTH_TOKEN="your-token-here"

# Option 2: Non-interactive login (if supported by your CI)
echo "password" | kumiho-cli login --email user@example.com

Development

Install from source

git clone https://github.com/kumihoclouds/kumiho-python.git
cd kumiho-python/kumiho-cli
pip install -e ".[dev]"

Run tests

pytest tests/

Troubleshooting

"No cached credentials found"

Run kumiho-cli login to authenticate.

"Token expired"

Run kumiho-cli refresh to get a fresh token.

"Permission denied" on credential file

chmod 600 ~/.kumiho/kumiho_authentication.json

Links

• Kumiho Cloud
• Documentation
• Python SDK
• Issue Tracker

License

Apache License 2.0 - see LICENSE for details.