cli-anything-codimd/CODIMD.md

CodiMD CLI Harness - Standard Operating Procedure

Overview

CodiMD is a collaborative markdown editor built on Node.js with real-time collaboration via Socket.IO. This document defines the standard operating procedure for building a CLI harness for CodiMD.

Architecture Summary

Technology Stack

• Backend: Node.js with Express
• Real-time: Socket.IO
• Database: Sequelize ORM (supports PostgreSQL, MySQL, MariaDB, SQLite, MSSQL)
• Authentication: Multiple providers (Facebook, Google, GitHub, Dropbox, Twitter, GitLab, LDAP, SAML, OAuth2, Email)

Data Models

Note

• id (UUID): Primary key
• shortid: Short unique identifier for sharing
• alias: Custom URL alias
• permission: One of: freely, editable, limited, locked, protected, private
• viewcount: Number of views
• title: Note title (extracted from content)
• content: Markdown content
• authorship: JSON array tracking contributions
• lastchangeAt: Last modification timestamp
• savedAt: Last save timestamp

User

• id (UUID): Primary key
• profileid: External profile ID
• profile: JSON profile data
• history: User history
• accessToken: OAuth access token
• refreshToken: OAuth refresh token
• deleteToken: Token for account deletion
• email: User email
• password: Hashed password

Revision

• id (UUID): Primary key
• patch: Diff-match-patch format
• lastContent: Previous content snapshot
• content: Full content at revision time
• length: Content length
• authorship: Authorship tracking

Permission Model

Permission	Description
freely	Anyone can view and edit
editable	Anyone can view, logged-in users can edit
limited	Logged-in users can view and edit
locked	Anyone can view, only owner can edit
protected	Logged-in users can view, only owner can edit
private	Only owner can view and edit

CLI Architecture

Command Groups

1. Note Commands (note)

• note list - List user's notes
• note get <id> - Get note content
• note create - Create new note
• note update <id> - Update note content
• note delete <id> - Delete note
• note publish <id> - Get publish link
• note info <id> - Get note metadata

2. User Commands (user)

• user me - Get current user info
• user export - Export user data
• user delete - Delete user account

3. Export Commands (export)

• export markdown <id> [file] - Export as markdown
• export pdf <id> [file] - Export as PDF (if enabled)
• export html <id> [file] - Export as HTML

4. Revision Commands (revision)

• revision list <id> - List note revisions
• revision get <id> <time> - Get note at specific time

State Management

The CLI maintains session state in ~/.config/cli-anything-codimd/:

• session.json: Auth tokens and session data
• config.json: Server configuration
• cache.json: Cached note metadata

Output Formats

All commands support --json flag for machine-readable output:

{
  "status": "success|error",
  "data": {...},
  "error": "error message if status is error"
}

Authentication Flow

1. Interactive login prompts for credentials
2. Supports all auth providers configured on server
3. Session token stored for subsequent commands
4. Token refresh handled automatically

Implementation Notes

1. Note ID Encoding: CodiMD uses base64url-encoded UUIDs. The CLI must handle encoding/decoding.
2. Real-time Limitations: The CLI cannot participate in real-time editing; it uses the REST API.
3. Permission Checks: All operations must verify permissions before execution.
4. Update Limitation: Note updates are only allowed when no users are actively editing via real-time connection.