31.6. How to use (individual commands)

31.6.2. Current node/relationship and path
31.6.3. Listing the contents of a node/relationship
31.6.4. Creating nodes and relationships
31.6.5. Setting, renaming and removing properties
31.6.6. Deleting nodes and relationships
31.6.7. Environment variables
31.6.8. Executing groovy/python scripts
31.6.9. Traverse
31.6.10. Query with Cypher
31.6.11. Indexing
31.6.12. Transactions

The shell is modeled after Unix shells like bash that you use to walk around your local file system. It has some of the same commands, like cd and ls. When you first start the shell (see instructions above), you will get a list of all the available commands. Use man <command> to get more info about a particular command. Some notes:


Single line comments, which will be ignored, can be made by using the prefix "//". Example:

// This is a comment

31.6.2. Current node/relationship and path

You have a current node/relationship and a "current path" (like a current working directory in bash) that you’ve traversed so far. You start at the reference node and can then cd your way through the graph (check your current path at any time with the pwd command). cd can be used in different ways:

  • cd <node-id> will traverse one relationship to the supplied node id. The node must have a direct relationship to the current node.
  • cd -a <node-id> will do an absolute path change, which means the supplied node doesn’t have to have a direct relationship to the current node.
  • cd -r <relationship-id> will traverse to a relationship instead of a node. The relationship must have the current node as either start or end point. To see the relationship ids use the ls -vr command on nodes.
  • cd -ar <relationship-id> will do an absolute path change which means the relationship can be any relationship in the graph.
  • cd will take you back to the reference node, where you started in the first place.
  • cd .. will traverse back one step to the previous location, removing the last path item from your current path (pwd).
  • cd start (only if your current location is a relationship). Traverses to the start node of the relationship.
  • cd end (only if your current location is a relationship). Traverses to the end node of the relationship.

31.6.3. Listing the contents of a node/relationship

List contents of the current node/relationship (or any other node) with the ls command. Please note that it will give an empty output if the current node/relationship has no properties or relationships (for example in the case of a brand new graph). ls can take a node id as argument as well as filters, see Section 31.4, “Filters” and for information about how to specify direction see Section 31.3, “Enum options”. Use man ls for more info.

31.6.4. Creating nodes and relationships

You create new nodes by connecting them with relationships to the current node. For example, mkrel -t A_RELATIONSHIP_TYPE -d OUTGOING -c will create a new node (-c) and draw to it an OUTGOING relationship of type A_RELATIONSHIP_TYPE from the current node. If you already have two nodes which you’d like to draw a relationship between (without creating a new node) you can do for example, mkrel -t A_RELATIONSHIP_TYPE -d OUTGOING -n <other-node-id> and it will just create a new relationship between the current node and that other node.

31.6.5. Setting, renaming and removing properties

Property operations are done with the set, mv and rm commands. These commands operates on the current node/relationship. * set <key> <value> with optionally the -t option (for value type) sets a property. Supports every type of value that Neo4j supports. Examples of a property of type int:

$ set -t int age 29

And an example of setting a double[] property:

$ set -t double[] my_values [1.4,12.2,13]

Example of setting a String property containing a JSON string:

mkrel -c -d i -t DOMAIN_OF --np "{'app':'foobar'}"
  • rm <key> removes a property.
  • mv <key> <new-key> renames a property from one key to another.

31.6.6. Deleting nodes and relationships

Deletion of nodes and relationships is done with the rmnode and rmrel commands. rmnode can delete nodes, if the node to be deleted still has relationships they can also be deleted by supplying -f option. rmrel can delete relationships, it tries to ensure connectedness in the graph, but relationships can be deleted regardless with the -f option. rmrel can also delete the node on the other side of the deleted relationship if it’s left with no more relationships, see -d option.

31.6.7. Environment variables

The shell uses environment variables a-la bash to keep session information, such as the current path and more. The commands for this mimics the bash commands export and env. For example you can at anytime issue a export STACKTRACES=true command to set the STACKTRACES environment variable to true. This will then result in stacktraces being printed if an exception or error should occur. List environment variables using env

31.6.8. Executing groovy/python scripts

The shell has support for executing scripts, such as Groovy and Python (via Jython). As of now the scripts (*.groovy, *.py) must exist on the server side and gets called from a client with for example, gsh --renamePerson 1234 "Mathias" "Mattias" --doSomethingElse where the scripts renamePerson.groovy and doSomethingElse.groovy must exist on the server side in any of the paths given by the GSH_PATH environment variable (defaults to .:src:src/script). This variable is like the java classpath, separated by a :. The python/jython scripts can be executed with the jsh in a similar fashion, however the scripts have the .py extension and the environment variable for the paths is JSH_PATH.

When writing the scripts assume that there’s made available an args variable (a String[]) which contains the supplied arguments. In the case of the renamePerson example above the array would contain ["1234", "Mathias", "Mattias"]. Also please write your outputs to the out variable, such as out.println( "My tracing text" ) so that it will be printed at the shell client instead of the server.

31.6.9. Traverse

You can traverse the graph with the trav command which allows for simple traversing from the current node. You can supply which relationship types (w/ regex matching) and optionally direction as well as property filters for matching nodes. In addition to that you can supply a command line to execute for each match. An example: trav -o depth -r KNOWS:both,HAS_.*:incoming -c "ls $n". Which means traverse depth first for relationships with type KNOWS disregarding direction and incoming relationships with type matching HAS_.\* and do a ls <matching node> for each match. The node filtering is supplied with the -f option, see Section 31.4, “Filters”. See Section 31.3, “Enum options” for the traversal order option. Even relationship types/directions are supplied using the same format as filters.

31.6.10. Query with Cypher

You can use Cypher to query the graph. For that, use the start command.


Cypher queries need to be terminated by a semicolon ;.

  • start n = node(0) return n; will give you a listing of the node with ID 0
  • cypher 1.8 start n = node(0) return n; will execute the query with the Cypher parser version 1.8
  • profile start n = node(0) return n; will execute the cypher query and display profiling information

31.6.11. Indexing

It’s possible to query and manipulate indexes via the index command. Example: index -i persons name (will index the name for the current node or relationship in the "persons" index).

  • -g will do exact lookup in the index and display hits. You can supply -c with a command to be executed for each hit.
  • -q will ask the index a query and display hits. You can supply -c with a command to be executed for each hit.
  • --cd will change current location to the hit from the query. It’s just a convenience for using the -c option.
  • --ls will do a listing of the contents for each hit. It’s just a convenience for using the -c option.
  • -i will index a key-value pair in an index for the current node/relationship. If no value is given the property value for that key for the current node is used as value.
  • -r will remove a key-value pair (if it exists) from an index for the current node/relationship. Key and value is optional.
  • -t will set the index type to work with, for example index -t Relationship --delete friends will delete the friends relationship index.

31.6.12. Transactions

It is useful to be able to test changes, and then being able to commit or rollback said changes.

Transactions can be nested. With a nested transaction, a commit does not write any changes to disk, except for the top level transaction. A rollback, however works regardless of the level of the transaction. It will roll back all open transactions.

  • begin transaction Starts a transaction.
  • commit Commits a transaction.
  • rollback Rollbacks all open transactions.