Skip to main content

Interactive command line shell for CouchDB

Project description

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 <kevin@idempotent.ca>`_.

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cdbcli-0.9.1.tar.gz (17.8 kB view details)

Uploaded Source

Built Distribution

cdbcli-0.9.1-py3-none-any.whl (35.4 kB view details)

Uploaded Python 3

File details

Details for the file cdbcli-0.9.1.tar.gz.

File metadata

  • Download URL: cdbcli-0.9.1.tar.gz
  • Upload date:
  • Size: 17.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for cdbcli-0.9.1.tar.gz
Algorithm Hash digest
SHA256 7fede909e8fc256cadfeae820fffe4a4cf4258ddc47b409917e77209db762585
MD5 70bfc4ed013ee661eef77b0959186938
BLAKE2b-256 ff7125fd3c4e152df91e2177302fb73bc5e6c85617175f206a1a179a65351d6c

See more details on using hashes here.

File details

Details for the file cdbcli-0.9.1-py3-none-any.whl.

File metadata

File hashes

Hashes for cdbcli-0.9.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bd056f2e50d5121ad379ee371d1399de8fd5a899018c43c4a3acf3ddb8544bcd
MD5 34559a1c5828b0a45d30363eaf5e78d8
BLAKE2b-256 b7ebb7b560e8ca62e46df43405da44074b23154df8e23090a833e23478e09e6f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page