kevinjqiu/cdbcli repository overview

⁠cdbcli - CouchDB Interactive Shell

.. image:: https://img.shields.io/pypi/v/cdbcli.svg⁠ :target: https://pypi.python.org/pypi/cdbcli⁠ :alt: Latest PyPI version

.. image:: https://travis-ci.org/kevinjqiu/cdbcli.svg?branch=master⁠ :target: https://travis-ci.org/kevinjqiu/cdbcli⁠ :alt: Latest Travis CI build status for master

.. image:: https://readthedocs.org/projects/cdbcli/badge/?version=latest⁠ :target: https://cdbcli.readthedocs.io/en/latest/⁠ :alt: Documentation Status

.. image:: https://coveralls.io/repos/github/kevinjqiu/cdbcli/badge.svg⁠ :target: https://coveralls.io/github/kevinjqiu/cdbcli⁠ :alt: Code Coverage

.. image:: https://img.shields.io/badge/license-Apache%202.0-blue.svg⁠ :target: LICENSE :alt: License

.. image:: https://img.shields.io/badge/docker-kevinjqiu%2Fcdbcli-blue.svg⁠ :target: https://hub.docker.com/r/kevinjqiu/cdbcli/⁠ :alt: Image on Docker Hub

.. image:: https://img.shields.io/badge/aur-cdbcli-blue.svg⁠ :target: https://aur.archlinux.org/packages/cdbcli/⁠ :alt: Arch User Repository

⁠Features

• auto-completion for database name, document id, view name, command
• syntax highlighting of documents and views
• navigate a couchdb server as if it were a file system
• various commands supported
  • cd - change database
  • ls - list docs under a database
  • cat - show content of a doc
  • exec - execute a view
  • rm - remove a doc
  • man - show help on commands
  • mkdir - create new database
  • du - doc and database size
  • lv - list views inside a view doc
• create/update docs using external $EDITOR
• pipe output to external shell commands, such as grep, wc and jq

⁠Demo

.. image:: https://asciinema.org/a/1mj2j4cxhqmq5m6t16tm82ws8.png⁠ :scale: 50% :target: https://asciinema.org/a/1mj2j4cxhqmq5m6t16tm82ws8⁠

⁠Usage

This tool allows you to traverse a CouchDB database as if it were a file system. Familiar file system commands are supported, such as ls, cd, mkdir, rm, etc, while providing context-rich auto-completion.

Starting cdbcli ^^^^^^^^^^^^^^^

Refer to the Installation_ section for guide on how to install cdbcli.

Running cdbcli requires connection parameters to the underlying couchdb instance you want to connnect to.

.. code::

cdbcli --help

Usage: cdbcli [OPTIONS] [DATABASE]

Options:
  -h, --host TEXT               The host of the couchdb instance
  --port TEXT                   The port of the coouchdb instance
  -u, --username TEXT           The username to connect as
  -p, --password TEXT           The password
  -P, --askpass / --no-askpass  Ask for password?
  --tls / --no-tls              Use TLS to connect to the couchdb instance?
  --help                        Show this message and exit.

e.g., if you want to connect your couchdb instance at http://yourdomain:9999⁠, you can issue the command::

cdbcli -h yourdomain --port 9999 -u admin -P

Specifying -P will prompt you for password. You can also use -p to specify password at the command line, but this is not recommended for sensitive passwords.

By default, cdbcli connects to the couchdb instance at http://localhost:5984⁠.

You will be greeted by the cdbcli's splash screen::

      ___  ____  ____   ___  __    ____
     / __)(  _ \(  _ \ / __)(  )  (_  _)
    ( (__  )(_) )) _ <( (__  )(__  _)(_
     \___)(____/(____/ \___)(____)(____)

    Welcome to cdbcli 0.1.1
    CouchDB version: 1.5.0

    Type 'help' or 'man' to get a list of all supported commands
    Press <TAB> for command auto-completion
    Press Ctrl+C or Ctrl+D or type 'exit' to exit

admin@yourdomain/>

Run with Docker ^^^^^^^^^^^^^^^

cdbcli is also available as a docker image on the docker hub <https://hub.docker.com/r/kevinjqiu/cdbcli/>_

To run::

docker run -it kevinjqiu/cdbcli cdbcli <arguments>

The docker networking restrictions apply, so if you want to connect to a database on localhost, e.g., you will need to let the container use the host's networking::

docker run -it --net=host kevinjqiu/cdbcli cdbcli <arguments>

⁠Installation

.. code::

pip install cdbcli

⁠Contributing

• Clone this repository.
• Make a Python virtualenv
• Install requirements: pip install -r requirements-test.txt
• Install docker <www.docker.com>_ because the integration tests require it
• Run make start_couchdb. This will start the testing couchdb instance using docker
• Run make test
• Run make stop_couchdb to clean up

Contributing to Documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

• Clone this repository.
• Make a Python virtualenv
• Install requirements: pip install -r requirements-docs.txt
• Run make docs. The documentation can be accessed under docs/build/index.html.

⁠Licence

cdbcli is licensed under Apache 2.0

⁠Authors

cdbcli was written by Kevin J. Qiu <[email protected]>_.

See all contributors <https://github.com/kevinjqiu/cdbcli/graphs/contributors>_

⁠Attribution

• python-prompt-toolkit <https://github.com/jonathanslenders/python-prompt-toolkit>_ by Jonathan Slenders
• click <http://click.pocoo.org/5/>_ by Armin Ronacher