Metadata-Version: 2.4
Name: mdwiki-cli
Version: 0.1.0
Summary: CLI client for the Markdown Content Service (LLM Wiki layer)
Author-email: 小棒 <chrodinian@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/USER/mdwiki-cli
Project-URL: Issues, https://github.com/USER/mdwiki-cli/issues
Keywords: markdown,wiki,obsidian,llm-agent,knowledge-base
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: responses>=0.24; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# mdwiki-cli

CLI client for the [Markdown Content Service](../README.md) — the Wiki layer of the
[Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern.

`mdwiki` is a thin REST wrapper for the Java/Spring Boot service that maintains
bidirectional wikilinks, versioned markdown documents, and Obsidian-compatible
exports.

## Install

```bash
pip install mdwiki-cli
```

Or with uv:

```bash
uvx --from mdwiki-cli mdwiki --help
```

Requires Python 3.11 or newer.

## Configure

Either env vars:

```bash
export MDWIKI_BASE_URL=http://localhost:8091/hft1
export MDWIKI_TOKEN=dev-admin-token
export MDWIKI_SPACE=wiki              # optional default space
```

Or `~/.config/mdwiki/config.toml`:

```toml
base_url = "http://localhost:8091/hft1"
token = "dev-admin-token"
space = "wiki"
timeout = 30

[profiles.prod]
base_url = "https://wiki.prod.example.com/hft1"
token = "prod-token"
```

Switch profile with `MDWIKI_PROFILE=prod`. Env vars override TOML.

## Quick start

```bash
mdwiki ping
mdwiki space ls
mdwiki ls --space wiki
mdwiki cat 42                          # markdown body to stdout
mdwiki context 42 --json               # full context for an agent

cat note.md | mdwiki new --space wiki --title "New" -f -
mdwiki put-content 42 -f revised.md
mdwiki rebuild-links --space wiki

mdwiki export wiki -o /tmp/wiki.zip
```

## Command groups

- `space` — list / get / new
- documents — `cat`, `show`, `context`, `ls`, `search`, `new`, `edit`,
  `put-content`, `versions`, `get-by-slug`
- links — `links`, `backlinks`, `rebuild-links`
- jobs — `job-status`, `job-logs`
- `export <space>` — Obsidian zip
- `recent` — local history of `cat`/`show`
- `skill path` — bundled SKILL.md absolute path

Run `mdwiki <cmd> --help` for full options.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | success |
| 1 | unexpected error |
| 2 | usage error |
| 3 | config / auth missing |
| 4 | API 4xx |
| 5 | API 5xx |
| 6 | optimistic lock conflict |

## Use with Claude Code

After installing the CLI, expose the bundled skill to Claude:

```bash
ln -s "$(mdwiki skill path)" ~/.claude/skills/using-mdwiki.md
```

Claude will then auto-invoke the skill when the user mentions wiki / mdwiki /
markdown knowledge base operations.

## Develop

```bash
git clone <repo>
cd mdwiki-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

End-to-end tests against a real REST server:

```bash
MDWIKI_E2E_BASE_URL=http://localhost:8091/hft1 \
MDWIKI_E2E_TOKEN=dev-admin-token \
pytest -m e2e
```

## Release

```bash
# Bump version in pyproject.toml
python -m build
twine upload dist/*
```

## License

MIT.
