.. Licensed under the Apache License, Version 2.0 (the "License"); you may not .. use this file except in compliance with the License. You may obtain a copy of .. the License at .. .. http://www.apache.org/licenses/LICENSE-2.0 .. .. Unless required by applicable law or agreed to in writing, software .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the .. License for the specific language governing permissions and limitations under .. the License. .. _intro/curl: ============================== cURL: Your Command Line Friend ============================== The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X, Windows, and many other platforms. ``curl`` provides easy access to the HTTP protocol (among others) directly from the command line and is therefore an ideal way of interacting with CouchDB over the HTTP REST API. For simple ``GET`` requests you can supply the URL of the request. For example, to get the database information: .. code-block:: bash shell> curl http://admin:password@127.0.0.1:5984 This returns the database information (formatted in the output below for clarity): .. code-block:: json { "couchdb": "Welcome", "version": "3.0.0", "git_sha": "83bdcf693", "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71", "features": [ "access-ready", "partitioned", "pluggable-storage-engines", "reshard", "scheduler" ], "vendor": { "name": "The Apache Software Foundation" } } .. note:: For some URLs, especially those that include special characters such as ampersand, exclamation mark, or question mark, you should quote the URL you are specifying on the command line. For example: .. code-block:: bash shell> curl 'http://couchdb:5984/_uuids?count=5' .. note:: On Microsoft Windows, use double-quotes anywhere you see single-quotes in the following examples. Use doubled double-quotes ("") anywhere you see single double-quotes. For example, if you see: .. code-block:: bash shell> curl -X PUT 'http://127.0.0.1:5984/demo/doc' -d '{"motto": "I love gnomes"}' you should replace it with: .. code-blocK:: bash shell> curl -X PUT "http://127.0.0.1:5984/demo/doc" -d "{""motto"": ""I love gnomes""}" If you prefer, ``^"`` and ``\"`` may be used to escape the double-quote character in quoted strings instead. You can explicitly set the HTTP command using the ``-X`` command line option. For example, when creating a database, you set the name of the database in the URL you send using a PUT request: .. code-block:: bash shell> curl -X PUT http://user:pass@127.0.0.1:5984/demo {"ok":true} But to obtain the database information you use a ``GET`` request (with the return information formatted for clarity): .. code-block:: bash shell> curl -X GET http://user:pass@127.0.0.1:5984/demo { "compact_running" : false, "doc_count" : 0, "db_name" : "demo", "purge_seq" : 0, "committed_update_seq" : 0, "doc_del_count" : 0, "disk_format_version" : 5, "update_seq" : 0, "instance_start_time" : "0", "disk_size" : 79 } For certain operations, you must specify the content type of request, which you do by specifying the ``Content-Type`` header using the ``-H`` command-line option: .. code-block:: bash shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids You can also submit 'payload' data, that is, data in the body of the HTTP request using the ``-d`` option. This is useful if you need to submit JSON structures, for example document data, as part of the request. For example, to submit a simple document to the ``demo`` database: .. code-block:: bash shell> curl -H 'Content-Type: application/json' \ -X POST http://user:pass@127.0.0.1:5984/demo \ -d '{"company": "Example, Inc."}' {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", "rev":"1-33b9fbce46930280dab37d672bbc8bb9"} In the above example, the argument after the ``-d`` option is the JSON of the document we want to submit. The document can be accessed by using the automatically generated document ID that was returned: .. code-block:: bash shell> curl -X GET http://user:pass@127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8 {"_id":"8843faaf0b831d364278331bc3001bd8", "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", "company":"Example, Inc."} The API samples in the :ref:`api/basics` show the HTTP command, URL and any payload information that needs to be submitted (and the expected return value). All of these examples can be reproduced using ``curl`` with the command-line examples shown above.