DevHub CLI: Your Personal Development Knowledge Hub

Welcome to DevHub CLI – a powerful command-line interface designed to help developers capture, organize, and retrieve their development insights effortlessly. Whether it's a tricky bug fix, a crucial architectural decision, a handy cheatsheet, or a brilliant new idea, DevHub CLI ensures your knowledge is always at your fingertips, stored locally and seamlessly synced with Notion.

✨ Features

DevHub CLI is built for a smooth developer experience, offering:

• Interactive Logging (dh log): Guided prompts to quickly document various types of entries (BUG, DECISION, CHEATSHEET, IDEA, PROCESS).
• Smart Search (dh find): Search entries by keywords, tags, and types. Results are presented in an interactive list.
• Interactive List (dh list): View your most recent entries in an interactive list.
• Seamless Actions: From the interactive search/list results, you can directly:
  • View Content (dh view): Render full entry content as formatted Markdown directly in your terminal.
  • Update Entries (dh update): Edit existing entries with pre-filled prompts.
  • Delete Entries (dh delete): Remove entries locally and archive them in Notion with a confirmation prompt.
  • Open in Notion (dh open-notion): Instantly jump to the corresponding Notion page in your browser or desktop app.
• Local-First Storage: All entries are stored as JSON files locally, ensuring data ownership and offline access.
• Notion Integration: Automatically syncs your entries to a Notion database, providing a rich web interface and collaborative features.
• Markdown Support: Content fields support Markdown, which is rendered beautifully in the terminal and Notion.

🚀 Getting Started

Follow these steps to set up and start using DevHub CLI.

Prerequisites

• Python 3.10+
• A Notion account
• A Notion Integration Token
• A Notion Database ID

1. Clone the Repository

git clone https://github.com/iamvusumzi/devhub.git
cd devhub

2. Set up Python Environment

It's recommended to use a virtual environment:

python -m venv venv
source venv/bin/activate # On Windows: `venv\Scripts\activate`
pip install -r requirements.txt

3. Configure Notion Integration

Create a .env file in the root of your devhub-api directory with the following variables:

NOTION_TOKEN="secret_YOUR_NOTION_INTEGRATION_TOKEN"
NOTION_DATABASE_ID="YOUR_NOTION_DATABASE_ID"

⚙️ Setup & Configuration

Follow these steps to connect DevHub to your Notion workspace.

1. Get your Notion Integration Token (NOTION_TOKEN)

The integration token allows the DevHub API to communicate with your workspace.

1. Go to the Notion My-Integrations page.
2. Click the + New integration button.
3. Name: Enter "DevHub".
4. Workspace: Select the workspace where you want to store your notes.
5. Type: Ensure it is set to Internal Integration.
6. Click Submit.
7. Under the Secrets tab, click Show and copy the Internal Integration Secret.

Note: This is your NOTION_TOKEN. Keep it private and never commit it to version control.

---

2. Grant Access to your Database

By default, your new integration has zero permissions. You must explicitly invite it to your database.

1. Open the specific Notion Database you created for DevHub.
2. Click the three dots (...) in the top-right corner of the page.
3. Scroll down to Connect to (or Add connections).
4. Search for your integration name ("DevHub").
5. Select it and click Confirm.

---

3. Find your Notion Database ID (NOTION_DATABASE_ID)

Every Notion database has a unique identifier hidden in its URL.

1. Open your database in a web browser.
2. Examine the URL. It will look similar to this: https://www.notion.so/myworkspace/86433384f447ed84390e9e4239e050?v=...
3. The Database ID is the 32-character string between the last slash (/) and the question mark (?).
   • In the example above, the ID is: 86433384f447ed84390e9e4239e050
4. Copy this string and add it to your .env file.

4. Set up Your Notion Database

Your Notion database needs specific properties for DevHub CLI to function correctly. Create a new database (or use an existing one) and add the following properties:

• Name: Title (Type: Title) - This is usually the default title property.
• Type: Select (Options: BUG, DECISION, CHEATSHEET, IDEA, PROCESS)
• Project: Select
• Tags: Multi-select
• DevHub ID: Rich text - Crucial for syncing and updating!

5. Run the FastAPI Backend

The CLI communicates with a local FastAPI server. Start it in a dedicated terminal:

python api/main.py

You should see output indicating the server is running on http://127.0.0.1:8000.

6. (Optional) Migrate Existing Notion Pages

If you have existing Notion pages that you want to link to your local DevHub entries (or vice-versa), run the migration script. This will backfill the DevHub ID property in Notion pages based on their titles.

python scripts/migrate_notion_ids.py

💻 Usage

All commands are accessed via the dh executable.

Log a New Entry

dh log

This will start an interactive prompt to guide you through creating a new entry.

Find Entries

Search by keyword, tags, or type. The results are interactive.

dh find "API hang" --type BUG --tag python
# Or just a keyword:
dh find "recursion error"

List Recent Entries

dh list
# List more entries:
dh list --limit 10

View an Entry

View the full content of an entry by its ID. (Often used after dh find or dh list.)

dh view <entry_id>

Update an Entry

Edit an existing entry by its ID. Prompts will be pre-filled with current data.

dh update <entry_id>

Delete an Entry

Permanently remove an entry from local storage and archive it in Notion. Requires confirmation.

dh delete <entry_id>

Open in Notion

Open the corresponding Notion page in your browser or desktop app.

dh open-notion <entry_id>

🤝 Contributing

Contributions are welcome! Feel free to open issues or pull requests.

---

Enjoy your enhanced development workflow with DevHub CLI!