<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>
<a href="https://pypi.org/project/graphc/"><img alt="PYPI version" src="https://img.shields.io/pypi/v/graphc?style=flat-square"></a>
<a href="https://github.com/dhth/graphc/releases/latest"><img alt="Latest Release" src="https://img.shields.io/github/release/dhth/graphc.svg?style=flat-square"></a>
<a href="https://github.com/dhth/graphc/releases"><img alt="Commits Since Latest Release" src="https://img.shields.io/github/commits-since/dhth/graphc/latest?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/cf/83/2bc6fdea0cd215a1979aa24c400680e30b47cf575b48f1fe6e826453e548/graphc-0.1.3.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 <a href=\"https://pypi.org/project/graphc/\"><img alt=\"PYPI version\" src=\"https://img.shields.io/pypi/v/graphc?style=flat-square\"></a>\n <a href=\"https://github.com/dhth/graphc/releases/latest\"><img alt=\"Latest Release\" src=\"https://img.shields.io/github/release/dhth/graphc.svg?style=flat-square\"></a>\n <a href=\"https://github.com/dhth/graphc/releases\"><img alt=\"Commits Since Latest Release\" src=\"https://img.shields.io/github/commits-since/dhth/graphc/latest?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.3",
"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": "887b25e073bc0694ee4a98fe3b1b0765f8685c46004aab7ddd7c95ef191fd749",
"md5": "711c5ad9120989eb065a9938aea6da30",
"sha256": "bd820f357a2c19664fa4aa9a6649f82d2cbd61ce58ecb5510f912bb1f2c9ad4f"
},
"downloads": -1,
"filename": "graphc-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "711c5ad9120989eb065a9938aea6da30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 15139,
"upload_time": "2025-08-03T11:37:41",
"upload_time_iso_8601": "2025-08-03T11:37:41.824061Z",
"url": "https://files.pythonhosted.org/packages/88/7b/25e073bc0694ee4a98fe3b1b0765f8685c46004aab7ddd7c95ef191fd749/graphc-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf832bc6fdea0cd215a1979aa24c400680e30b47cf575b48f1fe6e826453e548",
"md5": "43ed83d5f26d87a0cb13e49781aa332a",
"sha256": "c5821d488e28f65fd6eadccf88a575998ff31261f15067fc8425c9b1e2e6bc46"
},
"downloads": -1,
"filename": "graphc-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "43ed83d5f26d87a0cb13e49781aa332a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 14546,
"upload_time": "2025-08-03T11:37:42",
"upload_time_iso_8601": "2025-08-03T11:37:42.862120Z",
"url": "https://files.pythonhosted.org/packages/cf/83/2bc6fdea0cd215a1979aa24c400680e30b47cf575b48f1fe6e826453e548/graphc-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 11:37:42",
"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
