<p align="center">
<h1 align="center">graphc</h1>
<p align="center">
<a href="https://github.com/dhth/graphc/actions/workflows/main.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/dhth/graphc/main.yml?style=flat-square"></a>
</p>
</p>
`graphc` (stands for "graph console") lets you query Neo4j/AWS Neptune databases
via an interactive console.
💾 Installation
---
```sh
uv tool install graphc
```
⚡️ Usage
---
```text
usage: graphc [OPTIONS]
Query Neo4j/AWS Neptune databases via an interactive console
options:
-h, --help show this help message and exit
-q STRING, --query STRING
Cypher query to execute. If not provided, starts interactive console
-d STRING, --db-uri STRING
Database URI
-b, --benchmark Benchmark query execution times without showing results (only applicable in query mode)
-n INTEGER, --bench-num-runs INTEGER
Number of benchmark runs (default: 5)
-W INTEGER, --bench-warmup-num-runs INTEGER
Number of warmup runs before benchmarking (default: 0)
--debug Print debug information without doing anything
-w, --write Write query results to file (or start console with 'write results' mode on)
-f {json,csv}, --format {json,csv}
Output file format for query results
-p, --print-query Print the query (or start console with 'print query' mode on)
```
```bash
# Interactive mode
export DB_URI='bolt://127.0.0.1:7687'
export DB_USER='user'
export DB_PASSWORD='password'
graphc
graphc -d 'bolt://abc.xyz.us-east-1.neptune.amazonaws.com:8182'
# One-off query mode
graphc --query 'MATCH (n: Node) RETURN n.id, n.name LIMIT 5'
graphc -q - < query.cypher
echo 'MATCH (n: Node) RETURN n.id, n.name LIMIT 5' | graphc -q -
```
📟 Console
---
`graphc` comes with a console where you can execute queries in an interactive
manner.
### Commands
| Command(s) | Description |
|--------------------------------|---------------------------------|
| `help` / `:h` | show help |
| `clear` | clear screen |
| `quit` / `exit` / `bye` / `:q` | quit |
| `write <FORMAT>` | turn ON "write results" mode |
| `write off` | turn OFF "write results" mode |
| `@<filename>` | execute query from a local file |
| `print <on/off>` | toggle "print query" mode |
### Keymaps
| Key | Description |
|-----------|------------------------------------------------------------|
| `<esc>` | enter vim mode |
| `↑` / `k` | scroll up in query history |
| `↓` / `j` | scroll down in query history |
| `tab` | cycle through path suggestions (in insert mode, after `@`) |
✏️ Write mode
---
`graphc` lets you save query results to a file in both one-off query mode and
console mode.
```bash
cat query.cypher | graphc -q - --write
```
In console mode, use the command `write <FORMAT>` (format can be `csv` or
`json`).
`graphc` will save results in the directory it's run in, in a subdirectory
called `.graphc`.
🔢 Benchmarking
---
You can benchmark the execution times for a query using the `--benchmark/-b`
flag.
```bash
cat query.cypher | graphc -c - -b -n 5 -w 2
```
```text
Warming up (2 runs) ...
Warmup 1: 627.84 ms
Warmup 2: 452.06 ms
Benchmarking (5 runs) ...
Run 1: 451.92 ms
Run 2: 449.51 ms
Run 3: 451.52 ms
Run 4: 453.09 ms
Run 5: 445.73 ms
Statistics:
Mean: 450.35 ms
Median: 451.52 ms
Min: 445.73 ms
Max: 453.09 ms
```
Raw data
{
"_id": null,
"home_page": null,
"name": "graphc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "neo4j, neptune, graph, database, cypher, console, cli",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a4/52/1cb2d21ec1c46dfd0ee012c6a0131ebc90c671b9c619572b9a86fef3542c/graphc-0.1.2.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <h1 align=\"center\">graphc</h1>\n <p align=\"center\">\n <a href=\"https://github.com/dhth/graphc/actions/workflows/main.yml\"><img alt=\"Build status\" src=\"https://img.shields.io/github/actions/workflow/status/dhth/graphc/main.yml?style=flat-square\"></a>\n </p>\n</p>\n\n`graphc` (stands for \"graph console\") lets you query Neo4j/AWS Neptune databases\nvia an interactive console.\n\n\n\n\ud83d\udcbe Installation\n---\n\n```sh\nuv tool install graphc\n```\n\n\u26a1\ufe0f Usage\n---\n\n```text\nusage: graphc [OPTIONS]\n\nQuery Neo4j/AWS Neptune databases via an interactive console\n\noptions:\n -h, --help show this help message and exit\n -q STRING, --query STRING\n Cypher query to execute. If not provided, starts interactive console\n -d STRING, --db-uri STRING\n Database URI\n -b, --benchmark Benchmark query execution times without showing results (only applicable in query mode)\n -n INTEGER, --bench-num-runs INTEGER\n Number of benchmark runs (default: 5)\n -W INTEGER, --bench-warmup-num-runs INTEGER\n Number of warmup runs before benchmarking (default: 0)\n --debug Print debug information without doing anything\n -w, --write Write query results to file (or start console with 'write results' mode on)\n -f {json,csv}, --format {json,csv}\n Output file format for query results\n -p, --print-query Print the query (or start console with 'print query' mode on)\n```\n\n```bash\n# Interactive mode\nexport DB_URI='bolt://127.0.0.1:7687'\nexport DB_USER='user'\nexport DB_PASSWORD='password'\ngraphc\n\ngraphc -d 'bolt://abc.xyz.us-east-1.neptune.amazonaws.com:8182'\n\n# One-off query mode\ngraphc --query 'MATCH (n: Node) RETURN n.id, n.name LIMIT 5'\n\ngraphc -q - < query.cypher\n\necho 'MATCH (n: Node) RETURN n.id, n.name LIMIT 5' | graphc -q -\n```\n\n\ud83d\udcdf Console\n---\n\n`graphc` comes with a console where you can execute queries in an interactive\nmanner.\n\n\n\n### Commands\n\n| Command(s) | Description |\n|--------------------------------|---------------------------------|\n| `help` / `:h` | show help |\n| `clear` | clear screen |\n| `quit` / `exit` / `bye` / `:q` | quit |\n| `write <FORMAT>` | turn ON \"write results\" mode |\n| `write off` | turn OFF \"write results\" mode |\n| `@<filename>` | execute query from a local file |\n| `print <on/off>` | toggle \"print query\" mode |\n\n### Keymaps\n\n| Key | Description |\n|-----------|------------------------------------------------------------|\n| `<esc>` | enter vim mode |\n| `\u2191` / `k` | scroll up in query history |\n| `\u2193` / `j` | scroll down in query history |\n| `tab` | cycle through path suggestions (in insert mode, after `@`) |\n\n\u270f\ufe0f Write mode\n---\n\n`graphc` lets you save query results to a file in both one-off query mode and\nconsole mode.\n\n```bash\ncat query.cypher | graphc -q - --write\n```\n\nIn console mode, use the command `write <FORMAT>` (format can be `csv` or\n`json`).\n\n\n\n`graphc` will save results in the directory it's run in, in a subdirectory\ncalled `.graphc`.\n\n\ud83d\udd22 Benchmarking\n---\n\nYou can benchmark the execution times for a query using the `--benchmark/-b`\nflag.\n\n```bash\ncat query.cypher | graphc -c - -b -n 5 -w 2\n```\n\n```text\nWarming up (2 runs) ...\nWarmup 1: 627.84 ms\nWarmup 2: 452.06 ms\n\nBenchmarking (5 runs) ...\nRun 1: 451.92 ms\nRun 2: 449.51 ms\nRun 3: 451.52 ms\nRun 4: 453.09 ms\nRun 5: 445.73 ms\n\nStatistics:\nMean: 450.35 ms\nMedian: 451.52 ms\nMin: 445.73 ms\nMax: 453.09 ms\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "query graph databases via an interactive console",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://tools.dhruvs.space/graphc/",
"Issues": "https://github.com/dhth/graphc/issues",
"Repository": "https://github.com/dhth/graphc"
},
"split_keywords": [
"neo4j",
" neptune",
" graph",
" database",
" cypher",
" console",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2ba044d7cf5c4c5af8511bdcaf6aef7ea54374fb2c67e908ead4f9bfd4a9a501",
"md5": "d171d897bfcfa2de9314a2085d7f7977",
"sha256": "1e5486e191e65935c0e7c318a5fa820632d4c6384a2014c59e6b1dfbcd0c6961"
},
"downloads": -1,
"filename": "graphc-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d171d897bfcfa2de9314a2085d7f7977",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 14572,
"upload_time": "2025-08-02T20:51:33",
"upload_time_iso_8601": "2025-08-02T20:51:33.312247Z",
"url": "https://files.pythonhosted.org/packages/2b/a0/44d7cf5c4c5af8511bdcaf6aef7ea54374fb2c67e908ead4f9bfd4a9a501/graphc-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a4521cb2d21ec1c46dfd0ee012c6a0131ebc90c671b9c619572b9a86fef3542c",
"md5": "c6c10e972d25d97c251b676761c8a077",
"sha256": "2cdb40f33403ddfa69328e9494da41e10731f4dc0882c682636edf9e3dbd1b2e"
},
"downloads": -1,
"filename": "graphc-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c6c10e972d25d97c251b676761c8a077",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 13812,
"upload_time": "2025-08-02T20:51:34",
"upload_time_iso_8601": "2025-08-02T20:51:34.111674Z",
"url": "https://files.pythonhosted.org/packages/a4/52/1cb2d21ec1c46dfd0ee012c6a0131ebc90c671b9c619572b9a86fef3542c/graphc-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 20:51:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dhth",
"github_project": "graphc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "graphc"
}
JSON
