Cogit CLI

Local-first command-line tool for managing Cogits offline using the Cogit Protocol.

Cogit is like git, Sep is like gh - Cogit manages your knowledge locally, Sep syncs it to the cloud.

What is Cogit?

Cogit is a files-first CLI tool that lets you capture and organize your thoughts, ideas, and knowledge in markdown files following the Cogit Protocol v0.1.

Work offline, keep your thoughts organized, and sync when you're ready using Sep CLI.

Installation

npm install -g @septerional/cogit

Quick Start

1. Initialize a new Cogit

cogit init "My Project Ideas"

With options:

cogit init "Learning JavaScript" \
  --description "Notes and progress on learning JS" \
  --tags "learning,javascript,programming" \
  --private

This creates a .cogit.md file in your current directory with frontmatter metadata.

2. Add entries

Track your progress, questions, insights, and resources:

# Add progress update
cogit add progress "Completed the authentication module"

# Ask a question
cogit add question "Should I use REST or GraphQL for this API?"

# Document a key insight
cogit add synthesis "The best approach is to start simple and iterate based on feedback"

# Note a change in direction
cogit add adjustment "Switched from MySQL to PostgreSQL for better JSON support"

# Save a resource
cogit add resource "Great tutorial: https://example.com/guide"

3. View your Cogit

# See formatted view with icons
cogit show

# See raw markdown
cogit show --raw

4. Check status

cogit status

Shows metadata and entry statistics.

5. View entry history

# Show last 10 entries
cogit log

# Show last 20 entries
cogit log -n 20

Commands

cogit init [title]

Initialize a new Cogit in the current directory.

Options:

• -d, --description <text> - Cogit description
• -t, --tags <tags> - Comma-separated tags
• --private - Make the Cogit private

Examples:

# Simple cogit
cogit init "Daily Journal"

# With metadata
cogit init "API Design" \
  --description "REST API design patterns and decisions" \
  --tags "api,backend,design"

# Private cogit
cogit init "Personal Notes" --private

cogit add <type> <content>

Add an entry to the current Cogit.

Entry Types:

• progress - Track progress and updates
• question - Ask questions or raise doubts
• synthesis - Summarize conclusions or insights
• adjustment - Note changes in approach or direction
• resource - Share links, references, or resources

Examples:

cogit add progress "Finished implementing user authentication"
cogit add question "How should we handle rate limiting?"
cogit add synthesis "Users prefer simplicity over feature overload"
cogit add adjustment "Moving from sessions to JWT tokens"
cogit add resource "https://jwt.io/introduction"

cogit show

Display the current Cogit with formatted output.

Options:

• --raw - Show raw markdown instead of formatted view

Examples:

# Formatted view
cogit show

# Raw markdown
cogit show --raw

cogit status

Show status and metadata of the current Cogit.

Shows:

• File name
• Title and description
• Tags
• Visibility (public/private)
• Creation date
• Entry count by type

cogit log

Show entry history in reverse chronological order.

Options:

• -n, --number <count> - Number of entries to show (default: 10)

Examples:

# Show last 10 entries
cogit log

# Show last 50 entries
cogit log -n 50

Cogit Protocol v0.1

Cogit files follow the Cogit Protocol specification:

---
title: My Cogit
description: A description of what this cogit is about
tags:
  - tag1
  - tag2
private: false
created_at: '2026-04-06T23:00:00.000Z'
protocol_version: '0.1'
---

# My Cogit

A description of what this cogit is about

## progress

Your progress update goes here

## question

Your question goes here

## synthesis

Your synthesis goes here

Frontmatter Fields

• title - Cogit title (required)
• description - Brief description
• tags - Array of tags
• private - Boolean (true/false)
• created_at - ISO 8601 timestamp
• protocol_version - Protocol version (0.1)

Entry Types

Each entry is a level 2 heading (##) with one of these types:

• progress - Updates, accomplishments, completed tasks
• question - Questions, uncertainties, things to explore
• synthesis - Conclusions, insights, key takeaways
• adjustment - Changes in approach, pivots, corrections
• resource - Links, references, useful materials

Workflow

Local-First Workflow

1. Create: cogit init "Project Name"
2. Work: Add entries as you go with cogit add
3. Review: Use cogit show and cogit log to review progress
4. Sync: Use Sep CLI to sync to Septerional cloud

Integration with Sep CLI

Cogit is designed to work alongside Sep CLI:

• Cogit (this tool) - Local, offline-first, file-based
• Sep (sepcli) - Cloud sync, API interaction

# Work locally
cogit init "My Ideas"
cogit add progress "First draft done"

# Sync to cloud
sep push  # Coming soon

# Pull from cloud
sep pull  # Coming soon

File Structure

Each Cogit is a single .cogit.md file:

my-project/
  └── my-project-ideas.cogit.md

You can have multiple Cogits in different directories:

~/cogits/
  ├── learning-rust.cogit.md
  ├── project-ideas.cogit.md
  └── daily-journal.cogit.md

Why Cogit?

• Files-first: Your data in plain markdown, not locked in a database
• Offline: Work without internet, sync when ready
• Version control: Use git to version your cogits
• Portable: Standard markdown format, readable anywhere
• Protocol-based: Open specification anyone can implement

Requirements

• Node.js >= 18.0.0

Related Projects

• Sep CLI - Cloud sync tool for Septerional
• Septerional API - Developer API

License

MIT