mint-cli

A tiny CLI that helps you start new projects.

Without mint-cli:

mkdir my-project && cd my-project && git init
# ... stare at empty folder
# ... forget why you started this two weeks later

With mint-cli:

mint
> What are you trying to build?
> a cli to track my reading list

# Pick a name, land in your new project, docs/WHY.md already open

You get a name, a git repo, and a file that forces you to write down why you're building this — before you write any code.

What it does

• Asks what you're building
• Suggests 5 project names (or skip with mint my-project)
• Creates the directory, runs git init
• Creates docs/ with two files:
  • WHY.md — document your vision before coding
  • DECISIONS.md — log decisions as you build
• Opens WHY.md in your editor with a simple template:

## I'm building this because:
## I'm intentionally not solving:
## This will be done when:

That's it. You're in your project, ready to go.

Requirements

• Python 3.9+
• python-dotenv (required)
• openai + DigitalOcean API key (optional, for AI name suggestions)

Setup

Install dependencies

pip install python-dotenv

# Optional: for AI-powered name suggestions
pip install openai

Set your API key (optional)

For AI name suggestions, add this to your shell config (.zshrc, .bashrc, etc.):

export DIGITAL_OCEAN_MODEL_ACCESS_KEY="your_key_here"

Without an API key, mint-cli still works — it just asks you to type a name directly.

Usage

Quick setup

Add this to your ~/.zshrc or ~/.bashrc:

mint() {
    source /path/to/mint-cli/mint.sh
}

Interactive mode

Run with no arguments to get AI-suggested names:

Direct mode

Already know what you want to call it? Skip the AI:

This confirms the path and creates the project immediately.

Both modes create the project AND cd you into it automatically.

Example session

✨ mint-cli - Project Scaffolding

What are you trying to build?
> a cli tool to track my reading list

Generating name ideas...

Project name ideas:

  r. [Regenerate names]
  0. [Type your own name]
  1. book-shelf
  2. read-track
  3. page-turn
  4. my-reads
  5. list-lit

Pick a number (r to regenerate, 0 to type your own): 2

✅ Created ~/projects/read-track
✅ Initialized git repository
✅ Created docs/WHY.md
✅ Created docs/DECISIONS.md

Opening in nano...

Philosophy

• This is a helper, not a product
• Short-lived scripts are allowed to be small
• The output matters more than the tool
• If it stops being useful, delete it

Configuration

Edit config.py to customize:

BASE_PATH = os.path.expanduser("~/projects")  # Where projects are created
EDITOR = "nano"                                # Editor for WHY.md
NUM_SUGGESTIONS = 5                            # Number of name suggestions

License

MIT. Use it, modify it, or throw it away.