---
name: codimd
description: CLI harness for CodiMD collaborative markdown notes
version: 0.1.0
categories:
  - documentation
  - markdown
  - collaboration
entry_point: cli-anything-codimd
namespace: cli_anything.codimd
---

# CodiMD CLI Harness

A stateful CLI for CodiMD - collaborative markdown notes on all platforms.

## Installation

```bash
pip install cli-anything-codimd
```

## Quick Start

```bash
# Set server
cli-anything-codimd config set server https://your-codimd-server.com

# List your notes
cli-anything-codimd note list

# Create a new note
cli-anything-codimd note create --content "# My New Note\n\nHello world"

# Get note content
cli-anything-codimd note get <note-id>

# Export as markdown
cli-anything-codimd export markdown <note-id> --output note.md

# Export as PDF
cli-anything-codimd export pdf <note-id> --output note.pdf

# Get user info
cli-anything-codimd user me

# Interactive REPL mode
cli-anything-codimd repl
```

## Command Groups

### Note Commands (`note`)

| Command | Description |
|---------|-------------|
| `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 info <id>` | Get note metadata |
| `note publish <id>` | Get publish link |

### User Commands (`user`)

| Command | Description |
|---------|-------------|
| `user me` | Get current user info |
| `user login` | Login to server |
| `user logout` | Logout from session |
| `user export` | Export all user data |
| `user delete` | Delete user account |

### Export Commands (`export`)

| Command | Description |
|---------|-------------|
| `export markdown <id>` | Export as markdown |
| `export pdf <id>` | Export as PDF |
| `export html <id>` | Export as HTML |
| `export slide <id>` | Export as reveal.js slides |

### Revision Commands (`revision`)

| Command | Description |
|---------|-------------|
| `revision list <id>` | List note revisions |
| `revision get <id> <time>` | Get note at specific time |

### Config Commands (`config`)

| Command | Description |
|---------|-------------|
| `config get [key]` | Get configuration value |
| `config set <key> <value>` | Set configuration value |

## JSON Output Mode

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

```bash
cli-anything-codimd --json note list
```

Response format:
```json
{
  "status": "success|error",
  "data": {...},
  "error": "error message if status is error"
}
```

## Agent Integration Guide

### Authentication

The CLI stores session tokens in `~/.config/cli-anything-codimd/session.json`.
Agents should check authentication status before operations and handle `PermissionError` exceptions.

### Note ID Format

CodiMD uses multiple note ID formats:
- **UUID**: Full UUID (e.g., `12345678-1234-1234-1234-123456789012`)
- **Encoded**: base64url-encoded UUID (e.g., `VXDECB3HEXDPHWHGHFDGWEDFBM`)
- **Short ID**: Short identifier for sharing (e.g., `abc123`)

The CLI handles encoding/decoding automatically.

### 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 |

### Common Workflows

#### Create and Edit Note
```python
# Create note
result = subprocess.run(
    ["cli-anything-codimd", "--json", "note", "create", "--content", markdown],
    capture_output=True, text=True
)
data = json.loads(result.stdout)
note_id = data["data"]["id"]

# Update note
subprocess.run(
    ["cli-anything-codimd", "note", "update", note_id, "--content", new_markdown]
)
```

#### Export Note
```python
# Export to file
subprocess.run(
    ["cli-anything-codimd", "export", "markdown", note_id, "-o", "output.md"]
)
```

#### List Notes with Filtering
```python
# Get notes as JSON
result = subprocess.run(
    ["cli-anything-codimd", "--json", "note", "list"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)
notes = data["data"]["notes"]
```

## Server Configuration

The CLI can connect to any CodiMD instance:

```bash
# Set server URL
cli-anything-codimd config set server https://codimd.example.com

# Disable SSL verification (for self-signed certs)
cli-anything-codimd config set verify_ssl false

# Set request timeout
cli-anything-codimd config set timeout 60
```

Environment variables:
- `CODIMD_SERVER`: Default server URL
- `CLI_ANYTHING_FORCE_INSTALLED`: Use installed command instead of module path