Merge branch 'claude/fix-quickstart-command-FwS3d' into 'main'

fix(ci): use correct CLI command and run Node.js e2e tests on MRs; remove bash CLI

See merge request postgres-ai/postgres_ai!126

Author: NikolayS

.gitlab-ci.yml

@@ -94,84 +94,6 @@ reporter:tests:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_COMMIT_BRANCH == "main"'
 
-cli:smoke:test:
-  stage: test
-  image: alpine:3.20
-  variables:
-    GIT_STRATEGY: fetch
-  before_script:
-    - apk add --no-cache bash curl git docker-cli docker-compose
-  script:
-    - bash -n ./postgres_ai
-    - |
-      set -euo pipefail
-      out=$(./postgres_ai help | tr -d "\r")
-      echo "$out" | grep -q "Postgres AI CLI"
-      echo "$out" | grep -q "COMMANDS:"
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-
-cli:e2e:dind:
-  stage: test
-  image: alpine:3.20
-  services:
-    - name: docker:24-dind
-      command: ["--tls=false"]
-  needs:
-    - job: build:test:images
-  variables:
-    DOCKER_HOST: tcp://docker:2375
-    DOCKER_TLS_CERTDIR: ""
-    DOCKER_API_VERSION: "1.43"
-    GIT_STRATEGY: fetch
-    PGAI_TAG: ${CI_COMMIT_REF_SLUG}
-  before_script:
-    - apk add --no-cache bash curl git coreutils docker-cli docker-compose openssl
-    - docker version
-    # Pull images from GitLab Container Registry
-    - echo "$CI_REGISTRY_PASSWORD" | docker login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin
-    - |
-      echo "Pulling images from GitLab Container Registry..."
-      docker pull "$CI_REGISTRY_IMAGE/postgres-ai-configs:$PGAI_TAG"
-      docker pull "$CI_REGISTRY_IMAGE/reporter:$PGAI_TAG"
-      docker pull "$CI_REGISTRY_IMAGE/monitoring-flask-backend:$PGAI_TAG"
-      echo "Images ready:"
-      docker images | grep "$CI_REGISTRY_IMAGE"
-    # Create .env file with registry and tag
-    - |
-      cat > .env << EOF
-      PGAI_REGISTRY=$CI_REGISTRY_IMAGE
-      PGAI_TAG=$PGAI_TAG
-      EOF
-  script:
-    - set -euo pipefail
-    - bash -n ./postgres_ai
-    - ./postgres_ai check || true
-    - ./postgres_ai quickstart --demo -y
-    - timeout 60 ./postgres_ai status
-    - timeout 10 ./postgres_ai logs grafana || true
-    - ./postgres_ai config
-    - ./postgres_ai update-config
-    - ./postgres_ai list-instances || true
-    - ./postgres_ai add-key "test_key_123"
-    - ./postgres_ai show-key
-    - ./postgres_ai remove-key
-    - ./postgres_ai generate-grafana-password || true
-    - ./postgres_ai show-grafana-credentials || true
-    - ./postgres_ai add-instance "postgresql://postgres:postgres@target-db:5432/target_database" "ci-demo"
-    - ./postgres_ai test-instance "ci-demo" || true
-    - printf "y\n" | ./postgres_ai reset sink-postgres
-    - ./postgres_ai restart
-    - ./postgres_ai stop
-    - ./postgres_ai start
-    - printf "y\n" | ./postgres_ai reset
-    - ./postgres_ai clean
-  after_script:
-    - docker ps -a || true
-    - docker system prune -af || true
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-
 cli:node:smoke:
   stage: test
   image: node:20-alpine
@@ -465,10 +387,7 @@ cli:node:e2e:dind:
       docker images | grep "$CI_REGISTRY_IMAGE"
     # Create .env file with registry and tag
     - |
-      cat > .env << EOF
-      PGAI_REGISTRY=$CI_REGISTRY_IMAGE
-      PGAI_TAG=$PGAI_TAG
-      EOF
+      printf "%s\n" "PGAI_REGISTRY=$CI_REGISTRY_IMAGE" "PGAI_TAG=$PGAI_TAG" > .env
   script:
     - ./tests/e2e.cli.sh
   after_script:
@@ -509,13 +428,10 @@ cli:node:full:dind:
       docker images | grep "$CI_REGISTRY_IMAGE"
     # Create .env file with registry and tag
     - |
-      cat > .env << EOF
-      PGAI_REGISTRY=$CI_REGISTRY_IMAGE
-      PGAI_TAG=$PGAI_TAG
-      EOF
+      printf "%s\n" "PGAI_REGISTRY=$CI_REGISTRY_IMAGE" "PGAI_TAG=$PGAI_TAG" > .env
   script:
-    - echo "=== Testing quickstart (demo mode) ==="
-    - node ./cli/dist/bin/postgres-ai.js mon quickstart --demo
+    - echo "=== Testing local-install (demo mode) ==="
+    - node ./cli/dist/bin/postgres-ai.js mon local-install --demo
     - sleep 10
     - node ./cli/dist/bin/postgres-ai.js mon status
     - echo ""
@@ -535,6 +451,7 @@ cli:node:full:dind:
   after_script:
     - docker ps -a || true
   rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^feature\//'
   allow_failure: false
 

CONTRIBUTING.md

@@ -124,7 +124,7 @@ The demo DB is initialized by `config/target-db/init.sql` and creates the `monit
 PGPASSWORD='...' npx postgresai prepare-db postgresql://admin@host:5432/dbname
 ```
 
-- Add your instance to `instances.yml` (or use the helper CLI: `./postgres_ai add-instance 'postgresql://user:pass@host:port/db' my-db`)
+- Add your instance to `instances.yml` (or use the CLI: `postgresai mon targets add 'postgresql://user:pass@host:port/db' my-db`)
 - Make sure `is_enabled: true` for that instance.
 
 #### 2) Generate pgwatch sources from `instances.yml`
@@ -296,12 +296,12 @@ make up
 make up-local
 ```
 
-### Option A: Run via the `postgres_ai` script (recommended)
+### Option A: Run via the CLI (recommended)
 
-`postgres_ai` uses a single compose file path stored in `COMPOSE_FILE`. You can override it to include the local compose override:
+Use the CLI with `COMPOSE_FILE` to include the local compose override:
 
 ```bash
-COMPOSE_FILE="docker-compose.yml:docker-compose.local.yml" ./postgres_ai quickstart --demo -y
+COMPOSE_FILE="docker-compose.yml:docker-compose.local.yml" postgresai mon local-install --demo -y
 ```
 
 To rebuild on every run:
@@ -310,7 +310,7 @@ To rebuild on every run:
 COMPOSE_FILE="docker-compose.yml:docker-compose.local.yml" \
   docker compose -f docker-compose.yml -f docker-compose.local.yml build --no-cache
 
-COMPOSE_FILE="docker-compose.yml:docker-compose.local.yml" ./postgres_ai restart
+COMPOSE_FILE="docker-compose.yml:docker-compose.local.yml" postgresai mon restart
 ```
 
 ### Option B: Run Docker Compose directly
@@ -333,22 +333,22 @@ docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --force-r
 ### Reset everything
 
 ```bash
-./postgres_ai reset
+postgresai mon reset
 ```
 
 ### View logs
 
 ```bash
-./postgres_ai logs
-./postgres_ai logs grafana
-./postgres_ai logs monitoring_flask_backend
+postgresai mon logs
+postgresai mon logs grafana
+postgresai mon logs monitoring_flask_backend
 ```
 
 ### Stop / start
 
 ```bash
-./postgres_ai stop
-./postgres_ai start
+postgresai mon stop
+postgresai mon start
 ```
 
 

README.md

@@ -145,29 +145,29 @@ If you see errors like `permission denied` / `insufficient_privilege` / code `42
     npx postgresai prepare-db --print-sql -d mydb
     ```
 
-**One command setup:**
+**Install the CLI:**
 
 ```bash
-# Download the CLI
-curl -o postgres_ai https://gitlab.com/postgres-ai/postgres_ai/-/raw/main/postgres_ai \
-  && chmod +x postgres_ai
+npm install -g postgresai
 ```
 
-Now, start it and wait for a few minutes. To obtain a PostgresAI access token for your organization, visit https://console.postgres.ai (`Your org name → Manage → Access tokens`):
+**Start monitoring:**
+
+To obtain a PostgresAI access token for your organization, visit https://console.postgres.ai (`Your org name → Manage → Access tokens`):
 
 ```bash
 # Production setup with your Access token
-./postgres_ai quickstart --api-key=your_access_token
+postgresai mon local-install --api-key=your_access_token
 ```
 **Note:** You can also add your database instance in the same command:
 ```bash
-./postgres_ai quickstart --api-key=your_access_token --add-instance="postgresql://user:pass@host:port/DB"
+postgresai mon local-install --api-key=your_access_token --db-url="postgresql://user:pass@host:port/DB"
 ```
 
 Or if you want to just check out how it works:
 ```bash
 # Complete setup with demo database
-./postgres_ai quickstart --demo
+postgresai mon local-install --demo
 ```
 
 That's it! Everything is installed, configured, and running.
@@ -205,32 +205,32 @@ Failure to secure these ports may expose sensitive database information!
 
 **For developers:**
 ```bash
-./postgres_ai quickstart --demo
+postgresai mon local-install --demo
 ```
 Get a complete monitoring setup with demo data in under 2 minutes.
 
 **For production:**
 ```bash
-./postgres_ai quickstart --api-key=your_key
+postgresai mon local-install --api-key=your_key
 # Then add your databases
-./postgres_ai add-instance "postgresql://user:pass@host:port/DB"
+postgresai mon targets add "postgresql://user:pass@host:port/DB"
 ```
 
 ## 🔧 Management commands
 
 ```bash
 # Instance management
-./postgres_ai add-instance "postgresql://user:pass@host:port/DB"
-./postgres_ai list-instances
-./postgres_ai test-instance my-DB
+postgresai mon targets add "postgresql://user:pass@host:port/DB"
+postgresai mon targets list
+postgresai mon targets test my-DB
 
-# Service management  
-./postgres_ai status
-./postgres_ai logs
-./postgres_ai restart
+# Service management
+postgresai mon status
+postgresai mon logs
+postgresai mon restart
 
 # Health check
-./postgres_ai health
+postgresai mon health
 ```
 
 ## 📋 Checkup reports
@@ -297,9 +297,9 @@ postgres_ai monitoring generates automated health check reports based on [postgr
 
 ## 🌐 Access points
 
-After running quickstart:
+After running local-install:
 
-- **🚀 MAIN: Grafana Dashboard**: http://localhost:3000 (login: `monitoring`; password is shown at the end of quickstart)
+- **🚀 MAIN: Grafana Dashboard**: http://localhost:3000 (login: `monitoring`; password is shown at the end of local-install)
 
 Technical URLs (for advanced users):
 - **Demo DB**: postgresql://postgres:postgres@localhost:55432/target_database
@@ -309,27 +309,8 @@ Technical URLs (for advanced users):
 ## 📖 Help
 
 ```bash
-./postgres_ai help
-```
-
-### Node.js CLI (early preview)
-
-```bash
-# run without install
-node ./cli/bin/postgres-ai.js --help
-
-# local dev: install aliases into PATH
-npm --prefix cli install --no-audit --no-fund
-npm link ./cli
-postgres-ai --help
 postgresai --help
-pgai --help
-
-# or install globally after publish (planned)
-# npm i -g @postgresai/cli
-# postgres-ai --help
-# postgresai --help
-# pgai --help
+postgresai mon --help
 ```
 
 ## 🔑 PostgresAI access token

cli/bin/postgres-ai.ts

@@ -1185,17 +1185,33 @@ mon
 
     // Update .env with custom tag if provided
     const envFile = path.resolve(projectDir, ".env");
-    const imageTag = opts.tag || pkg.version;
 
-    // Build .env content
-    const envLines: string[] = [`PGAI_TAG=${imageTag}`];
-    // Preserve GF_SECURITY_ADMIN_PASSWORD if it exists
+    // Build .env content, preserving important existing values
+    // Read existing .env first to preserve CI/custom settings
+    let existingTag: string | null = null;
+    let existingRegistry: string | null = null;
+    let existingPassword: string | null = null;
+
     if (fs.existsSync(envFile)) {
       const existingEnv = fs.readFileSync(envFile, "utf8");
+      // Extract existing values
+      const tagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
+      if (tagMatch) existingTag = tagMatch[1].trim();
+      const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
+      if (registryMatch) existingRegistry = registryMatch[1].trim();
       const pwdMatch = existingEnv.match(/^GF_SECURITY_ADMIN_PASSWORD=(.+)$/m);
-      if (pwdMatch) {
-        envLines.push(`GF_SECURITY_ADMIN_PASSWORD=${pwdMatch[1]}`);
-      }
+      if (pwdMatch) existingPassword = pwdMatch[1].trim();
+    }
+
+    // Priority: CLI --tag flag > existing .env > package version
+    const imageTag = opts.tag || existingTag || pkg.version;
+
+    const envLines: string[] = [`PGAI_TAG=${imageTag}`];
+    if (existingRegistry) {
+      envLines.push(`PGAI_REGISTRY=${existingRegistry}`);
+    }
+    if (existingPassword) {
+      envLines.push(`GF_SECURITY_ADMIN_PASSWORD=${existingPassword}`);
     }
     fs.writeFileSync(envFile, envLines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
 

config/Dockerfile

@@ -25,7 +25,7 @@ COPY pgwatch-postgres/metrics.yml /postgres_ai_configs/pgwatch/metrics.yml
 COPY pgwatch-prometheus/metrics.yml /postgres_ai_configs/pgwatch-prometheus/metrics.yml
 COPY prometheus/ /postgres_ai_configs/prometheus/
 COPY sink-postgres/ /postgres_ai_configs/sink-postgres/
-# Demo DB – used only for `quickstart --demo`
+# Demo DB – used only for `mon local-install --demo`
 COPY target-db/ /postgres_ai_configs/target-db/
 
 # Copy infrastructure scripts (entrypoints, generators, etc.)