neo4j-aura-provisioning-skill

name	neo4j-aura-provisioning-skill
description	Use when programmatically creating, pausing, resuming, resizing, or deleting Neo4j Aura instances: Aura CLI (aura-cli), Aura REST API, or scripted provisioning in CI/CD pipelines. Also covers downloading credentials, listing tenants, and managing instance lifecycles. Does NOT cover Cypher queries or application code — use neo4j-cypher-skill or driver skills. Does NOT cover general CLI tools (neo4j-admin, cypher-shell) — use neo4j-cli-tools-skill.
status	draft
version	0.1.0
allowed-tools	Bash, WebFetch

Neo4j Aura Provisioning Skill

Status: Draft / WIP — Content is a placeholder. Reference files and Aura API details to be added. Fetch current API reference: https://neo4j.com/docs/aura/platform/api/specification/

When to Use

• Creating a Neo4j Aura instance programmatically (CLI, API, Python script)
• Managing instance lifecycle: pause, resume, resize, delete
• Downloading credentials and .env files from the Aura Console or API
• Listing tenants and instances in a CI/CD pipeline
• Provisioning Aura for automated testing environments

When NOT to Use

• Cypher queries against a running database → use neo4j-cypher-skill
• Application driver setup → use a driver skill (python, javascript, java, etc.)
• neo4j-admin / cypher-shell / CLI tools → use neo4j-cli-tools-skill

---

Setup

pip install aura-cli       # Python CLI
aura-cli auth login        # opens browser for OAuth; saves token to ~/.aura/credentials

Or use environment variables for headless/CI:

export AURA_CLIENT_ID=<client-id>
export AURA_CLIENT_SECRET=<client-secret>

---

Core CLI Commands (Step-by-Step)

Step 1 — List tenants:

aura-cli tenants list

Step 2 — Create instance (capture output immediately):

# Add --format json to capture credentials programmatically
aura-cli instances create \
  --name "my-instance" \
  --region us-east-1 \
  --cloud-provider aws \
  --type free-db \
  --tenant-id <tenant-id> \
  --format json | tee aura-creds.json
# Initial password is shown ONCE here. Save aura-creds.json immediately.
# If lost: you must delete and recreate the instance — there is no password reset.

Step 3 — Wait for RUNNING status (with timeout):

for i in $(seq 1 60); do
  STATUS=$(aura-cli instances get --instance-id <id> --format json | jq -r '.status')
  echo "Attempt $i: $STATUS"
  [ "$STATUS" = "running" ] && break
  [ $i -eq 60 ] && echo "TIMEOUT: instance did not start after 10 min" && exit 1
  sleep 10
done

Step 4 — Write .env:

cat <<EOF > .env
NEO4J_URI=neo4j+s://<instance-id>.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=<password>
NEO4J_DATABASE=neo4j
EOF
grep -q '.env' .gitignore || echo '.env' >> .gitignore

Step 5 — Verify connectivity:

source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
  "RETURN 'connected' AS status"

---

Aura Free Limitations

If provisioning a free-db instance, be aware:

• Max 200,000 nodes and 400,000 relationships
• No GDS (Graph Data Science) — suggest neo4j-gds-skill only for Pro/Enterprise
• No read replicas or clustering
• Instance pauses after 3 days of inactivity (auto-resumes on connection)

---

Checklist

• .env created with credentials and added to .gitignore
• Instance status is running before attempting connection
• Credentials printed/displayed only once at creation — save them immediately
• aura-cli auth login or AURA_CLIENT_ID/AURA_CLIENT_SECRET env vars configured
• Tenant ID specified for all operations (required in multi-tenant accounts)

---

Fetching Current Docs

https://neo4j.com/docs/llms.txt     ← full documentation index (includes Aura API spec)
https://neo4j.com/docs/aura/platform/api/specification/  ← live Aura REST API spec

References

• Aura Docs
• Aura CLI Docs
• Aura REST API Specification
• Aura CLI GitHub
• GraphAcademy: AuraDB Fundamentals