# Vimwiki Command-Line Interface
[][1]
[][2]
[][2]
[][3]
`vimwiki-cli` is a command-line interface to [Vimwiki][4], a plugin for the
[Vim][5] text editor. It provides a front-end for interactive editor commands
and can be used to automate repetitive tasks such as rebuilding tag metadata and
generating links, all from the command line.
[](https://asciinema.org/a/413921?autoplay=1)
## Installation
`vimwiki-cli` is available on [PyPI][2] and can be installed locally using the
Python Package Installer:
$ python -m pip install --user vimwiki-cli
Once installed, issue `vimwiki --help` to see usage.
## Configuration
For most installations no configuration is needed, however several environment
variables are available to modify default behavior without the need to pass
global options on the command line:
| Environment Variable | Global Option | Description |
| ---------------------- | ---------------- | ------------------------------------------------- |
| `VIMWIKI_EDITOR` | `--editor` | Editor to launch, defaults to `$EDITOR` or `vim`. |
| `VIMWIKI_COUNT` | `--count` | Index of wiki to open. |
| `VIMWIKI_SELECT` | `--select` | Select wiki from interactive list. |
| `VIMWIKI_OPEN_MATCHES` | `--open-matches` | Open search results by default. |
| `VIMWIKI_OPEN_TABS` | `--open-tabs` | Open pages in a new tab by default. |
## Advanced
### Supported Commands
Each CLI command corresponds to one or more Ex commands executed in the editor.
The following table details the mapping between these commands:
| CLI Command | Ex Commands |
| --------------------------------------- | ------------------------------------------------------------------- |
| `vimwiki` | `:VimwikiIndex` |
| `vimwiki all-html` | `:VimwikiIndex \| VimwikiAll2HTML` |
| `vimwiki check-links` | `:VimwikiIndex \| VimwikiCheckLinks` |
| `vimwiki diary` | `:VimwikiDiaryIndex` |
| `vimwiki diary generate-links` | `:VimwikiDiaryIndex \| VimwikiDiaryGenerateLinks` |
| `vimwiki diary today` | `:VimwikiMakeDiaryNote` |
| `vimwiki diary tomorrow` | `:VimwikiMakeTomorrowDiaryNote` |
| `vimwiki diary yesterday` | `:VimwikiMakeYesterdayDiaryNote` |
| `vimwiki generate-links PAGE PATTERN` | `:VimwikiIndex \| VimwikiGoto PAGE \| VimwikiGenerateLinks PATTERN` |
| `vimwiki goto PAGE` | `:VimwikiIndex \| VimwikiGoto PAGE` |
| `vimwiki help` | `:help vimwiki.txt \| only` |
| `vimwiki search PATTERN` | `:VimwikiIndex \| VimwikiSearch PATTERN` |
| `vimwiki tags generate-links PAGE TAGS` | `:VimwikiIndex \| VimwikiGoto PAGE \| VimwikiGenerateTagLinks TAGS` |
| `vimwiki tags rebuild` | `:VimwikiIndex \| VimwikiRebuildTags` |
| `vimwiki tags search PATTERN` | `:VimwikiIndex \| VimwikiSearchTags PATTERN` |
### Shell Completion
Shell completion is available for `bash`, `fish`, and `zsh` shells. To generate
an activation script, issue:
$ env _VIMWIKI_COMPLETE=source_$(basename $SHELL) vimwiki >/path/to/vimwiki-complete.sh
Once generated, the activation script may be sourced directly or from the shell
startup file to provide completion:
$ . /path/to/vimwiki-complete.sh
### Git Integration
For wikis managed with Git, a pre-commit hook script is available that executes
non-interactive commands to rebuild tag metadata and generate links before
commit.
The pre-commit hook relies on the following configuration options:
| Configuration Option | Description |
| ---------------------------- | ---------------------------------------------- |
| `vimwiki.options` | Extra options to pass to the `vimwiki` command |
| `vimwiki.linkspage` | Page which contains generated links |
| `vimwiki.taglinkspage` | Page which contains generated tag links |
| `vimwiki.generatelinks` | Generate links before commit (bool) |
| `vimwiki.generatediarylinks` | Generate diary links before commit (bool) |
| `vimwiki.generatetaglinks` | Generate tag links before commit (bool) |
| `vimwiki.rebuildtags` | Rebuild tag metadata before commit (bool) |
| `vimwiki.allhtml` | Convert wiki to HTML before commit (bool) |
For example, to configure the hook to rebuild tag metadata and generate tag
links in the `Tags` page before commit, issue:
$ git config vimwiki.taglinkspage Tags
$ git config vimwiki.generatetaglinks true
$ git config vimwiki.rebuildtags true
To enable the hook, copy or link [pre-commit.sh][6] to `.git/hooks/pre-commit`
in the wiki directory. Alternatively, if [pre-commit][8] is installed, add a
`pre-commit` configuration file, `.pre-commit-config.yaml` and run
`pre-commit autoupdate` to enable the latest version of the hook.
```yaml
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
- repo: https://github.com/sstallion/vimwiki-cli
rev: v1.1.0
hooks:
- id: vimwiki-cli
```
## Contributing
Pull requests are welcome! See [CONTRIBUTING.md][7] for more details.
## License
Source code in this repository is licensed under a Simplified BSD License. See
[LICENSE][3] for more details.
[1]: https://github.com/sstallion/vimwiki-cli/actions/workflows/ci.yml
[2]: https://pypi.org/project/vimwiki-cli/
[3]: https://github.com/sstallion/vimwiki-cli/blob/master/LICENSE
[4]: https://vimwiki.github.io/
[5]: https://www.vim.org/
[6]: https://github.com/sstallion/vimwiki-cli/blob/master/scripts/pre-commit.sh
[7]: https://github.com/sstallion/vimwiki-cli/blob/master/CONTRIBUTING.md
[8]: https://pre-commit.com/index
Raw data
{
"_id": null,
"home_page": "https://github.com/sstallion/vimwiki-cli",
"name": "vimwiki-cli",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "cli vim vimwiki wiki",
"author": "Steven Stallion",
"author_email": "sstallion@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/08/0b/882131aa3d4512bf74a28424bc1ee7f9bdbe2d88803061b3d811f249339f/vimwiki-cli-1.2.0.tar.gz",
"platform": null,
"description": "# Vimwiki Command-Line Interface\n\n[][1]\n[][2]\n[][2]\n[][3]\n\n`vimwiki-cli` is a command-line interface to [Vimwiki][4], a plugin for the\n[Vim][5] text editor. It provides a front-end for interactive editor commands\nand can be used to automate repetitive tasks such as rebuilding tag metadata and\ngenerating links, all from the command line.\n\n[](https://asciinema.org/a/413921?autoplay=1)\n\n## Installation\n\n`vimwiki-cli` is available on [PyPI][2] and can be installed locally using the\nPython Package Installer:\n\n $ python -m pip install --user vimwiki-cli\n\nOnce installed, issue `vimwiki --help` to see usage.\n\n## Configuration\n\nFor most installations no configuration is needed, however several environment\nvariables are available to modify default behavior without the need to pass\nglobal options on the command line:\n\n| Environment Variable | Global Option | Description |\n| ---------------------- | ---------------- | ------------------------------------------------- |\n| `VIMWIKI_EDITOR` | `--editor` | Editor to launch, defaults to `$EDITOR` or `vim`. |\n| `VIMWIKI_COUNT` | `--count` | Index of wiki to open. |\n| `VIMWIKI_SELECT` | `--select` | Select wiki from interactive list. |\n| `VIMWIKI_OPEN_MATCHES` | `--open-matches` | Open search results by default. |\n| `VIMWIKI_OPEN_TABS` | `--open-tabs` | Open pages in a new tab by default. |\n\n## Advanced\n\n### Supported Commands\n\nEach CLI command corresponds to one or more Ex commands executed in the editor.\nThe following table details the mapping between these commands:\n\n| CLI Command | Ex Commands |\n| --------------------------------------- | ------------------------------------------------------------------- |\n| `vimwiki` | `:VimwikiIndex` |\n| `vimwiki all-html` | `:VimwikiIndex \\| VimwikiAll2HTML` |\n| `vimwiki check-links` | `:VimwikiIndex \\| VimwikiCheckLinks` |\n| `vimwiki diary` | `:VimwikiDiaryIndex` |\n| `vimwiki diary generate-links` | `:VimwikiDiaryIndex \\| VimwikiDiaryGenerateLinks` |\n| `vimwiki diary today` | `:VimwikiMakeDiaryNote` |\n| `vimwiki diary tomorrow` | `:VimwikiMakeTomorrowDiaryNote` |\n| `vimwiki diary yesterday` | `:VimwikiMakeYesterdayDiaryNote` |\n| `vimwiki generate-links PAGE PATTERN` | `:VimwikiIndex \\| VimwikiGoto PAGE \\| VimwikiGenerateLinks PATTERN` |\n| `vimwiki goto PAGE` | `:VimwikiIndex \\| VimwikiGoto PAGE` |\n| `vimwiki help` | `:help vimwiki.txt \\| only` |\n| `vimwiki search PATTERN` | `:VimwikiIndex \\| VimwikiSearch PATTERN` |\n| `vimwiki tags generate-links PAGE TAGS` | `:VimwikiIndex \\| VimwikiGoto PAGE \\| VimwikiGenerateTagLinks TAGS` |\n| `vimwiki tags rebuild` | `:VimwikiIndex \\| VimwikiRebuildTags` |\n| `vimwiki tags search PATTERN` | `:VimwikiIndex \\| VimwikiSearchTags PATTERN` |\n\n### Shell Completion\n\nShell completion is available for `bash`, `fish`, and `zsh` shells. To generate\nan activation script, issue:\n\n $ env _VIMWIKI_COMPLETE=source_$(basename $SHELL) vimwiki >/path/to/vimwiki-complete.sh\n\nOnce generated, the activation script may be sourced directly or from the shell\nstartup file to provide completion:\n\n $ . /path/to/vimwiki-complete.sh\n\n### Git Integration\n\nFor wikis managed with Git, a pre-commit hook script is available that executes\nnon-interactive commands to rebuild tag metadata and generate links before\ncommit.\n\nThe pre-commit hook relies on the following configuration options:\n\n| Configuration Option | Description |\n| ---------------------------- | ---------------------------------------------- |\n| `vimwiki.options` | Extra options to pass to the `vimwiki` command |\n| `vimwiki.linkspage` | Page which contains generated links |\n| `vimwiki.taglinkspage` | Page which contains generated tag links |\n| `vimwiki.generatelinks` | Generate links before commit (bool) |\n| `vimwiki.generatediarylinks` | Generate diary links before commit (bool) |\n| `vimwiki.generatetaglinks` | Generate tag links before commit (bool) |\n| `vimwiki.rebuildtags` | Rebuild tag metadata before commit (bool) |\n| `vimwiki.allhtml` | Convert wiki to HTML before commit (bool) |\n\nFor example, to configure the hook to rebuild tag metadata and generate tag\nlinks in the `Tags` page before commit, issue:\n\n $ git config vimwiki.taglinkspage Tags\n $ git config vimwiki.generatetaglinks true\n $ git config vimwiki.rebuildtags true\n\nTo enable the hook, copy or link [pre-commit.sh][6] to `.git/hooks/pre-commit`\nin the wiki directory. Alternatively, if [pre-commit][8] is installed, add a\n`pre-commit` configuration file, `.pre-commit-config.yaml` and run\n`pre-commit autoupdate` to enable the latest version of the hook.\n\n```yaml\n# See https://pre-commit.com for more information\n# See https://pre-commit.com/hooks.html for more hooks\nrepos:\n - repo: https://github.com/sstallion/vimwiki-cli\n rev: v1.1.0\n hooks:\n - id: vimwiki-cli\n```\n\n## Contributing\n\nPull requests are welcome! See [CONTRIBUTING.md][7] for more details.\n\n## License\n\nSource code in this repository is licensed under a Simplified BSD License. See\n[LICENSE][3] for more details.\n\n[1]: https://github.com/sstallion/vimwiki-cli/actions/workflows/ci.yml\n[2]: https://pypi.org/project/vimwiki-cli/\n[3]: https://github.com/sstallion/vimwiki-cli/blob/master/LICENSE\n[4]: https://vimwiki.github.io/\n[5]: https://www.vim.org/\n[6]: https://github.com/sstallion/vimwiki-cli/blob/master/scripts/pre-commit.sh\n[7]: https://github.com/sstallion/vimwiki-cli/blob/master/CONTRIBUTING.md\n[8]: https://pre-commit.com/index\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Vimwiki Command-Line Interface",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/sstallion/vimwiki-cli"
},
"split_keywords": [
"cli",
"vim",
"vimwiki",
"wiki"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "14a62e394eb999f476356d34db11803d116d3656d959eb4c9015dde3aeaa0787",
"md5": "deba8966c7c86e333dc6fe2ffd11cf6a",
"sha256": "4ca178419897bf5af88d3a88debaf43b4f3f5f27f22d3c0278c18668977784a0"
},
"downloads": -1,
"filename": "vimwiki_cli-1.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "deba8966c7c86e333dc6fe2ffd11cf6a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 14931,
"upload_time": "2024-02-12T18:35:30",
"upload_time_iso_8601": "2024-02-12T18:35:30.837572Z",
"url": "https://files.pythonhosted.org/packages/14/a6/2e394eb999f476356d34db11803d116d3656d959eb4c9015dde3aeaa0787/vimwiki_cli-1.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "080b882131aa3d4512bf74a28424bc1ee7f9bdbe2d88803061b3d811f249339f",
"md5": "f84734a30cd173c4c38094aa3eec98b2",
"sha256": "9243b10f5cc85dac08d471f3b6ee9e4f48f513d2e356d2452545a50394ababad"
},
"downloads": -1,
"filename": "vimwiki-cli-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f84734a30cd173c4c38094aa3eec98b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15771,
"upload_time": "2024-02-12T18:35:32",
"upload_time_iso_8601": "2024-02-12T18:35:32.671467Z",
"url": "https://files.pythonhosted.org/packages/08/0b/882131aa3d4512bf74a28424bc1ee7f9bdbe2d88803061b3d811f249339f/vimwiki-cli-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 18:35:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sstallion",
"github_project": "vimwiki-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vimwiki-cli"
}
JSON
