Home

Awesome

cycli Build Status PyPi version

A command-line interface for Neo4j's graph query language, Cypher.

<p align="center"> <img src="screenshots/output.gif" /> </p>

Install

If you haven't already, download and install Neo4j. Then, install cycli:

$ pip install cycli

Start

To start, simply execute cycli from your terminal. Neo4j needs to be running.

$ cycli

If you have Neo4j authentication enabled, you'll need to pass a username.

$ cycli -u username

You will then be prompted to enter your password. For more options, execute cycli --help.

$ cycli --help
Usage: cycli [OPTIONS]

Options:
  -v, --version            Show cycli version and exit.
  -h, --host TEXT          The host address of Neo4j.
  -P, --port TEXT          The port number on which Neo4j is listening.
  -u, --username TEXT      Username for Neo4j authentication.
  -p, --password TEXT      Password for Neo4j authentication.
  -t, --timeout INTEGER    Set a global socket timeout for queries.
  -l, --logfile FILENAME   Log every query and its results to a file.
  -f, --filename FILENAME  Execute semicolon-separated Cypher queries from a
                           file.
  -s, --ssl                Use the HTTPS protocol.
  -r, --read-only          Do not allow any write queries.
  --help                   Show this message and exit.

Autocomplete

The smart autocompletion suggests node labels when you're drawing a node, relationship types when you're drawing a relationship, and properties when working with identifiers. Of course, it also suggests all of the Cypher keywords, functions, and predicates.

Node Labels

labels

Relationship Types

rels

Properties

props

Cypher Keywords

Cypher keywords are displayed in a probabilistic order based on your most recent keyword.

cypher

Opening Characters

If you type (, [, {, ", or ', a matching closing character is automatically placed to the right of your cursor.

matching

Syntax Highlighting

Catch syntax errors with the built-in syntax highlighting. The colors were chosen to emulate the syntax highlighting available in the Neo4j browser.

syntax

Usage

Execute Queries

Execute queries by ending them with a semicolon and pressing enter or by pressing enter twice.

Keywords

Type "help" to see a table of keywords / keystrokes and their descriptions.

KeywordDescription
quitExit cycli.
exitExit cycli.
helpDisplay this text.
refreshRefresh schema cache.
run-nRun a Cypher query n times.
exportSet a parameter with export key=value.
schemaDisplay indexes, constraints, labels, and relationship types.
schema-indexesDisplay indexes.
schema-constraintsDisplay constraints.
schema-labelsDisplay labels.
schema-relsDisplay relationship types.
CTRL-DExit cycli if the input is blank.
CTRL-CAbort and rollback the currently-running query.

run-n

Run a Cypher query n times. This is useful for large updates, e.g. if you want to update a property in batches.

> MATCH (n) RETURN COUNT(*);
   | COUNT(*)
---+----------
 1 |      456

26 ms

Let's say we want to add a new property in batches of 100. If we have 456 nodes, we'll need to run the same Cypher query 5 times.

> run-5 MATCH (n)
WHERE NOT HAS(n.newProperty)
WITH n LIMIT 100
SET n.newProperty = "Hello World"
RETURN COUNT(*);
   | COUNT(*)
---+----------
 1 |      100

Run 1: 44 ms

   | COUNT(*)
---+----------
 1 |      100

Run 2: 8 ms

   | COUNT(*)
---+----------
 1 |      100

Run 3: 8 ms

   | COUNT(*)
---+----------
 1 |      100

Run 4: 10 ms

   | COUNT(*)
---+----------
 1 |       56

Run 5: 9 ms

Total duration: 79 ms

export

Set parameters with export key=value.

> export name="Tom Hanks"
> export year=2005
> env
name=Tom Hanks
year=2005
> MATCH (p:Person {name:{name}})-[:ACTED_IN]->(m:Movie)
WHERE m.released > {year}
RETURN m.title, m.released;
   | m.title              | m.released
---+----------------------+------------
 1 | Charlie Wilson's War |       2007
 2 | Cloud Atlas          |       2012
 3 | The Da Vinci Code    |       2006

12 ms

The value is evaluated with Python's eval, so you can also do things like this:

> export evens=[x for x in range(10) if x % 2 == 0]
> env["evens"]
[0, 2, 4, 6, 8]

Credits

This project depends heavily on python-prompt-toolkit and py2neo. I also frequently reference the pgcli and mycli projects for ideas and troubleshooting help. The logo was designed by Greta Workman. =)

<p align="center"> <img src="screenshots/logo.png" /> </p>