cmddocs
is an interactive commandline wiki. It lets you easily maintain your docs/cheetsheets/notes using:
- Plain Text Files
- Write
markdown
in your local Editor - View in your local Pager
- Versioning with
git
cmddocs is like a framework around your plaintext files.
I kind of started cmddocs
because I couldn't find something like this on the internet. Here's my usecase. Im working as a DevOps guy being in touch with various types of software, languages, tools, operating systems and databases. To remember all those things I need a place to store commands, workflows and short howtos.
Most of the software I use (and love) runs on a OpenBSD Box on the internet and are commandline-based. These are mutt, taskwarrior, jrnl, weechat and so on...But i was missing a tool for documentation.
After switching to just plaintext files using vim
and git
it was also a bit annoying. So I wrote cmddocs
to make it easier for me to handle my plaintext files.
cmddocs
uses the mistune lexer to wrap markdown with ansi control sequences instead of html tags.
It looks something like this.
To give you an idea what it looks/feels like I created a short terminal recording.
pip install cmddocs
Also make sure you have tree installed.
Create .cmddocsrc
file in your $HOME with the following content (adjust to your needs):
[General]
Datadir = /home/noqqe/Docs
Default_Commit_Message = small changes
Excludedir = .git/
Editor = /usr/local/bin/vim
# EditorFlags = -C
Pager = /usr/bin/less
PagerFlags = -fr
Prompt = cmddocs>
Promptcolor = 37
Intro_Message = cmddocs - press ? for help
Mail = mail@example.org
Default_Extension = md
[Colors]
Header12 = 37
Header345 = 37
Codeblock = 92
The only required option is "Datadir", everything else will be guessed or defaults to a sane default value. Once you start cmddocs.py the CLI will be shown. Use help
for commands.
At first, create a very minimal config, like
[General]
Datadir = /home/noqqe/Docs
Editor = /usr/local/bin/vim
Pager = /usr/bin/less
Then you can start using cmddocs.
$ cmddocs
cmddocs - press ? for help
cmddocs> help
Documented commands (type help <topic>):
========================================
EOF delete e help list mail pwd search undo
cd diff edit info log move revert stats version
d dirs exit l ls mv rm status view
cmddocs> help l
Show files in current working dir
cmddocs> help log
Show git logs of your docs.
Usage: log # default loglines: 10)
log 20 # show 20 loglines
log 20 article # show log for specific article
log databases/mongodb 3 # same
Change directory
Usage:
cd Programming/
cd
Delete an article
Usage:
delete databases/mongodb
rm databases/mssql
Show directories in current working dir
Usage:
dirs
d
dirs Databases/
Edit or create new article.
Usage:
edit databases/mongodb
edit intro
Show files in current working dir
Usage:
list
l
list Databases/
Move an article to a new location
Usage:
move databases/mongodb databases/MongoDB
move life/foo notes/foo
mv life/foo notes/foo
View an article. Creates temporary file with converted markdown to ansi colored output. Opens your PAGER. (Only less supported atm)
Usage:
view databases/mongodb
view intro
Mail an article to a friend
Usage:
mail databases/mongodb
Recipient: mail@example.net
mail programming/r/loops
mail intro
Show current directory
Usage:
pwd
Search for keyword in current directory
Usage:
search mongodb
search foo
undo
, revert
-------------------
You can revert your changes (use revert from git)
:
Usage:
undo HEAD
undo 355f375
Will ask for confirmation.
Show git diffs between files and commits
Usage:
diff 7 # show diff for last 7 changes
diff 1 article # show diff for last change to article
diff # show last 5 diffs
Show infos for an article
Usage:
info article
info Databases/mongodb
Created: 2014-01-18 11:18:03 +0100
Updated: 2015-10-23 14:14:44 +0200
Commits: 26
Lines: 116
Words: 356
Characters: 2438
Show git logs of your docs.
Usage:
log # default loglines: 10)
log 20 # show 20 loglines
log 20 article # show log for specific article
log databases/mongodb 3 # same
Show git repo status of your docs
Usage:
status
Calculate some statistics on your docs
Usage:
stats
Exit cmddocs
Usage:
exit
List available commands with "help" or detailed help with "help cmd".
Show version of cmddocs
Usage:
version
See Changelog.
See License.