Keyflow CLI

A command-line interface for scaffolding and managing Keyflow projects.

Installation

You can use the Keyflow CLI without installing it globally by using npx:

npx keyflow-cli init

Or install it globally:

npm install -g keyflow-cli

Usage

Initialize a New Project

The init command scaffolds a new Keyflow project by cloning a template repository and setting up the initial configuration.

# Interactive mode
npx keyflow init

# Specify project name
npx keyflow init my-project

# Specify project path
npx keyflow init ./projects/my-new-project

# With options
npx keyflow init my-project --api-key kf_your_api_key --ngrok-url https://abc123.ngrok.io

Command Options

keyflow init [project-name]

Creates a new Keyflow project.

Arguments:

• project-name (optional) - Name or path for the new project

Options:

• -k, --api-key <key> - Keyflow API key (optional)
• -n, --ngrok-url <url> - Ngrok URL for local development (optional)
• -h, --help - Display help for command

Interactive Prompts:

If not provided as arguments, the CLI will prompt you for:

1. Project Name/Path: The name of your project or a path where it should be created

   • If you provide a path (e.g., ./projects/my-app), the project will be created at that location
   • If you provide just a name, it will be created in the current directory

2. Keyflow API Key (optional): Your Keyflow API key for authentication

   • Format should start with kf_
   • Can be skipped by pressing Enter

3. Ngrok URL (optional): Your ngrok tunnel URL for local development

   • Should be a valid HTTP/HTTPS URL
   • Can be skipped by pressing Enter

Examples

Basic Project Creation

# Create a project in current directory
npx keyflow init my-keyflow-app

# Create a project in a specific path
npx keyflow init ./projects/my-keyflow-app

# Interactive mode - will prompt for all options
npx keyflow init

With Configuration

# Provide API key and ngrok URL upfront
npx keyflow init my-app \
  --api-key kf_1234567890abcdef \
  --ngrok-url https://abc123.ngrok.io

Project Structure

After running keyflow init, your project will have the following structure:

my-keyflow-project/
├── src/
├── package.json
├── .env                 # Contains your API key and ngrok URL (if provided)
├── .env.example         # Template for environment variables
├── .gitignore
└── README.md

Environment Configuration

The CLI automatically creates environment files:

• .env - Contains your actual configuration (not committed to git)
• .env.example - Template showing required environment variables

Environment Variables

• KEYFLOW_API_KEY - Your Keyflow API key
• NGROK_URL - Your ngrok tunnel URL for local development

Development

Building the CLI

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode
pnpm dev

# Test the CLI locally
node dist/cli.js init test-project

Project Structure

src/
├── cli.ts              # Main CLI entry point
├── commands/           # Command implementations
│   └── init.ts         # Init command logic
├── utils/              # Utility functions
│   └── helpers.ts      # Helper functions
└── index.ts            # Package exports

Dependencies

• @clack/prompts - Beautiful CLI prompts
• commander - Command-line framework
• chalk - Terminal styling
• simple-git - Git operations
• fs-extra - Enhanced file system operations
• ora - Loading spinners

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Add tests if applicable
5. Run the build: pnpm build
6. Test your changes: node dist/cli.js init test-project
7. Commit your changes: git commit -am 'Add new feature'
8. Push to the branch: git push origin feature/new-feature
9. Create a Pull Request

Troubleshooting

Common Issues

Git not found

Error: git command not found

Make sure Git is installed and available in your PATH.

Permission denied

Error: EACCES: permission denied

Make sure you have write permissions to the target directory.

Template repository not found

Error: Repository not found

The template repository might be private or the URL might be incorrect.

Getting Help

• Use keyflow --help to see all available commands
• Use keyflow init --help to see options for the init command
• Check the Keyflow documentation for more information

License

UNLICENSED

Changelog

0.1.0

• Initial release
• Added init command for project scaffolding
• Interactive prompts for project configuration
• Support for API key and ngrok URL configuration