pgedgecli

package module
v0.5.0-beta.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2026 License: PostgreSQL Imports: 3 Imported by: 0

README

pgEdge Labs

pgEdge CLI

CI

pgedge is the unified command-line interface for the pgEdge product suite: pgedge <module> <resource> <verb>.

Modules: starfleet (Starfleet authentication and account resources, plus the nested byoc and managed infrastructure sub-trees) and controlplane (Control Plane).

Install

Releases are published on GitHub Releases. To ask a question or report a problem, open a GitHub issue. docs/getting-started.md covers first steps.

Hand the install to an AI agent

Paste the prompt below into your coding agent (Claude Code, Cursor, and the like) and it installs the CLI, wires up shell completion, and adds the agent skills for the products you use, asking you which those are along the way. It needs curl, plus Node.js for the skills step, and it stops on any failure rather than improvising.

Install the pgEdge CLI on this machine and set up its agent skills.
Follow these steps exactly, in order. If a step fails, stop and show
me the error. Do not improvise an alternative.

1. Preflight: check `curl` and `npx` exist. If `curl` is missing,
   stop and tell me it is needed for step 2. If `npx` is missing,
   stop and tell me Node.js is needed for step 4.
2. Install the CLI (no sudo, ever): run
   `curl -fsSL https://raw.githubusercontent.com/pgEdge/pgedge-cli/main/install.sh | sh`.
   The script verifies the release before installing it. Its
   `Installed pgedge <tag> to <path>` line names the binary's full
   path: use that path for `pgedge` in the rest of these steps. If
   the script warns that the directory is not on my PATH, append the
   `export PATH=...` line it prints to the rc file of my login shell
   (`~/.zshrc` for zsh, `~/.bashrc` for bash, creating it if missing,
   and skipping if the line is already there), and tell me you did.
3. Shell completion: the script runs `pgedge completion install`.
   If its output says a line still needs adding to my rc file, add
   that line once.
4. Ask me this question and wait for my answer. Do not guess it:
   "Which pgEdge products do you use: Starfleet, Control Plane, or
   both?" Then install the matching agent skills into the current
   project:
   - starfleet: `npx -y skills add pgEdge/pgedge-cli -s pgedge -s pgedge-starfleet -s pgedge-byoc -s pgedge-managed -y`
   - control plane: `npx -y skills add pgEdge/pgedge-cli -s pgedge -s pgedge-controlplane -y`
   - both: `npx -y skills add pgEdge/pgedge-cli -y`
5. Verify, and show me the output of each: `pgedge version`,
   `pgedge doctor` (both at the full path from step 2), and
   `npx -y skills list`. A doctor warning about missing credentials
   is expected on a fresh install. The next step after this setup
   is `pgedge starfleet auth login` (starfleet) or reading `pgedge llms controlplane`
   (control plane).
Install script (Linux, macOS)

Downloads the latest release for your platform, verifies its checksum (and its cosign signature when cosign is installed), and installs to /usr/local/bin (falling back to ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/pgEdge/pgedge-cli/main/install.sh | sh
Homebrew (macOS, Linux)

One command, once the tap is published:

brew install pgEdge/tap/pgedge

Available once the pgEdge/homebrew-tap repository is published.

go install

Go builds it from source at the main branch:

go install github.com/pgEdge/pgedge-cli/cmd/pgedge@main

Put a release tag in place of @main to build that release. A binary installed this way reports its version as dev.

Manual download

Grab the archive for your platform from the releases page, then verify and extract it:

# verify integrity
sha256sum -c checksums.txt --ignore-missing

# verify authenticity (optional, requires cosign)
cosign verify-blob \
    --certificate checksums.txt.pem \
    --signature checksums.txt.sig \
    --certificate-identity-regexp \
        '^https://github\.com/pgEdge/pgedge-cli/\.github/workflows/release\.yml@refs/tags/' \
    --certificate-oidc-issuer \
        'https://token.actions.githubusercontent.com' \
    checksums.txt

tar -xzf pgedge_*.tar.gz
install pgedge /usr/local/bin/

Builds are published for linux and darwin (amd64, arm64) and windows (amd64, arm64). Archive names are lower-case and use Go's architecture spelling, which uname does not reliably match: the mapping is irregular across platforms and shells, agreeing on some and not others. Take the name from the releases page rather than assembling one from uname output. Windows archives are .zip, and everything else is .tar.gz.

Build from source

Build the binary in a checkout and run it:

make build
./pgedge --help
Updating

A downloaded release binary updates itself with pgedge self update. See the Updating section below and docs/updating.md. A Homebrew install or a binary inside a git checkout is updated by the tool that owns it. pgedge version prints what you are running.

Updating

A downloaded release binary updates itself:

pgedge self update           # verify the newest release and swap it in
pgedge self update --check   # just say whether one exists

The command checks the download against the release's Sigstore signature and checksum before that download touches the installed binary, and it regenerates an installed completion script afterward. It leaves a Homebrew install or a binary inside a git checkout alone and names the command to run instead (brew upgrade pgedge, make build). pgedge doctor also reports the latest release. Details in Updating the CLI.

Shell completion

Enable Tab completion for commands, subcommands, and flags:

pgedge completion install

This detects your shell (bash, zsh, fish or PowerShell) and sets completion up one of two ways. The install script runs it automatically, and Homebrew will too once the tap (see above) is published.

  • File install (default). Writes a completion script into the directory your shell loads completions from, and prints any remaining step (a zsh fpath line, a PowerShell profile line). Nothing runs at shell start. pgedge self update regenerates the script, so it keeps up with the binary.
  • rc line (--rc-only). Appends one line to your shell's startup file and writes no script. The installed binary generates the completions at every shell start, so they can never be out of step with it, at roughly 10-20 ms on a warm cache.

The second route:

pgedge completion install --rc-only

The lines it adds, if you would rather add one by hand:

# ~/.bashrc
eval "$(pgedge completion bash)"

# ~/.zshrc
eval "$(pgedge completion zsh)"

# ~/.config/fish/config.fish
pgedge completion fish | source

# PowerShell $PROFILE
pgedge completion powershell | Out-String | Invoke-Expression

pgedge completion uninstall removes whichever of the two is in place.

Any shell's script can also be printed on its own for manual wiring:

pgedge completion fish
pgedge completion powershell

Release archives also ship a completions/ directory with a script per shell, including pgedge.ps1 for Windows zip users who prefer to wire it up manually.

AI-agent skills

pgEdge ships agent skills (SKILL.md, the Agent Skills open standard) in the skills/ directory of this repository:

  • skills/pgedge: pgedge CLI orientation and module choice
  • skills/pgedge-starfleet: Starfleet authentication, invites, and team memberships
  • skills/pgedge-byoc: pgEdge BYOC resources
  • skills/pgedge-managed: pgEdge-hosted managed databases
  • skills/pgedge-controlplane: pgEdge Control Plane resources

The pgedge binary does not install them, because skills are a layer above the CLI.

One command installs all five and detects your agent:

npx skills add pgEdge/pgedge-cli

It writes to .agents/skills/, the shared location supporting agents read, and symlinks it for those with their own convention, so Claude Code, Cursor, Copilot, Amp, Antigravity and a dozen others pick them up from a single install. Project scope is the default, putting them in the repository so teammates and cloud agents share the setup. Add --global for a per-user install. npx skills list, update and remove manage them afterward, and skills-lock.json pins each one by content hash.

For a single skill:

npx skills add pgEdge/pgedge-cli --skill pgedge-managed

Manual copy (any agent, no Node required):

git clone https://github.com/pgEdge/pgedge-cli
mkdir -p .agents/skills
cp -r pgedge-cli/skills/* .agents/skills/

Use ~/.claude/skills/ in place of .agents/skills/ to install for Claude Code alone.

Quickstart

Print the command tree, then sign in:

pgedge --help
pgedge starfleet auth login

Documentation

The docs/ tree carries the guides and the generated command reference: getting started, authentication and profiles, CI and automation, troubleshooting, versions, uninstall and support, per-module guides under docs/starfleet/, docs/managed/, docs/byoc/ and docs/controlplane/, and per-module reference pages in docs/reference/. AI agents should run pgedge llms instead, the same reference embedded in the binary.

Versioning

pgedge version reports the launcher version plus one per module, and what its first line reads depends on how the binary was built. The versions, uninstall and support page has the detail.

Uninstall

pgedge completion uninstall removes the shell completion script. The versions, uninstall and support page lists everything else the CLI put on the machine and where.

Development

Build, test and lint the checkout:

make build test lint

See CONTRIBUTING.md.

Documentation

Overview

Package pgedgecli embeds the AI-facing index shipped in this repository so the binary can serve it anywhere it is installed, without a checkout of the repo.

Only the INDEX lives here. Each module embeds its own reference document alongside its code (internal/<module>/llms.txt), reached through module.Module's Reference method and printed by `pgedge llms <module>`. That split is deliberate: a single llms-full.txt covering every module cost an agent roughly 40k tokens to look up one flag, and it made module scope something the doc gates had to infer rather than read off the file it was in.

Agent skills live in the repo's skills/ tree and are distributed via external, format-native installers (see the README) — they are NOT embedded in the binary.

Index

Constants

View Source 
const IndexSizeBudget = 28 * 1024

IndexSizeBudget bounds the size of the top-level llms.txt index.

The index exists because printing every module's reference cost the whole of that reference to look up one flag -- 314 KB across the four module documents as of this writing, and it only grows. Every section added to the index makes it a little more like the monolith it replaced, and before this budget there was no signal that a writer was spending against anything -- the design comment above cited a figure that had drifted to more than twice its stated value (#306).

It is set at the current size plus headroom, not at some ideal: the point is to make growth deliberate and visible, not to force a rewrite. Raising it is a fine thing to do on purpose, in a commit that says why.

The MODULE references are deliberately exempt. They are the targeted second read -- an agent reaches one only after the index has told it which -- so their size is paid by a caller who already knows they want that module, and byoc's is 131 KB precisely because it can be.

Variables

View Source 
var LLMS []byte

LLMS is the AI-agent index (llms.txt), printed by `pgedge llms`.

Functions

func Pages 

func Pages() ([]module.Document, error)

Pages returns the root's own pages, one per top-level command group (`pgedge llms inspect`), without the index. They keep the index small: a task pays for a command's page only when it runs it.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gendocs command
Command gendocs regenerates the AI-agent reference documents from the live cobra tree.
 Command gendocs regenerates the AI-agent reference documents from the live cobra tree.
pgedge command
vendorspec command
Command vendorspec captures the published per-product OpenAPI contracts into openapi/.
 Command vendorspec captures the published per-product OpenAPI contracts into openapi/.
internal
apicall
Package apicall is the raw request behind `pgedge starfleet api` and `pgedge controlplane api`: one HTTP call to a path under the module's API base, over the module's own authenticated client, with the module's own status-to-exit mapping and the CLI's output formats.
 Package apicall is the raw request behind `pgedge starfleet api` and `pgedge controlplane api`: one HTTP call to a path under the module's API base, over the module's own authenticated client, with the module's own status-to-exit mapping and the CLI's output formats.
apidefaults
Package apidefaults owns platform-level API defaults: the pgEdge Starfleet base URL and its resolution rule (flag > profile > default).
 Package apidefaults owns platform-level API defaults: the pgEdge Starfleet base URL and its resolution rule (flag > profile > default).
atomicfile
Package atomicfile replaces a file in one step, so a reader arriving mid-write sees the whole old file or the whole new one and never a truncated one.
 Package atomicfile replaces a file in one step, so a reader arriving mid-write sees the whole old file or the whole new one and never a truncated one.
auth
Package auth resolves API credentials and manages cached access tokens per profile and module under ~/.pgedge/cli/cache/.
 Package auth resolves API credentials and manages cached access tokens per profile and module under ~/.pgedge/cli/cache/.
cli
clitest
Package clitest assembles the full pgedge command tree for build-gate tests.
 Package clitest assembles the full pgedge command tree for build-gate tests.
config
Package config loads and saves the pgedge CLI configuration at ~/.pgedge/cli/config.yaml with named profiles carrying per-module sections.
 Package config loads and saves the pgedge CLI configuration at ~/.pgedge/cli/config.yaml with named profiles carrying per-module sections.
controlplane
Package controlplane implements the pgEdge Control Plane module of the unified pgedge CLI.
 Package controlplane implements the pgEdge Control Plane module of the unified pgedge CLI.
controlplane/api
Package api provides primitives to interact with the openapi HTTP API.
 Package api provides primitives to interact with the openapi HTTP API.
controlplane/cmd
Package cmd wires the pgEdge Control Plane command tree: the module root, its persistent connection flags, and the HTTP API client shared by every resource command.
 Package cmd wires the pgEdge Control Plane command tree: the module root, its persistent connection flags, and the HTTP API client shared by every resource command.
controlplane/svccfg
Package svccfg is a hand-written mirror of the Control Plane's per-service-type config key sets (mcp, rag, postgrest) at the CP release KeysFloor names.
 Package svccfg is a hand-written mirror of the Control Plane's per-service-type config key sets (mcp, rag, postgrest) at the CP release KeysFloor names.
docgen
Package docgen renders the command reference, the llms pages and the docs/reference pages, from the live cobra tree.
 Package docgen renders the command reference, the llms pages and the docs/reference pages, from the live cobra tree.
dryrun
Package dryrun records what a mutating command WOULD have sent, and stops it from being sent.
 Package dryrun records what a mutating command WOULD have sent, and stops it from being sent.
errbody
Package errbody repairs one specific lie an upstream proxy tells: an error response whose body is not JSON, served under a JSON Content-Type.
 Package errbody repairs one specific lie an upstream proxy tells: an error response whose body is not JSON, served under a JSON Content-Type.
httplog
Package httplog renders HTTP requests and responses to a diagnostic stream at an ordered level, and is the one place in this CLI that decides what must never be printed.
 Package httplog renders HTTP requests and responses to a diagnostic stream at an ordered level, and is the one place in this CLI that decides what must never be printed.
inspect
Package inspect runs read-only diagnostic queries against a Postgres database and renders the rows.
 Package inspect runs read-only diagnostic queries against a Postgres database and renders the rows.
inspect/inspecttest
Package inspecttest is a database/sql driver that answers queries from a script, so a command that runs an inspect analysis can be tested without a Postgres.
 Package inspecttest is a database/sql driver that answers queries from a script, so a command that runs an inspect analysis can be tested without a Postgres.
keychain
Package keychain stores the Starfleet client secret in the operating system's credential store: macOS Keychain, the Secret Service on Linux, Credential Manager on Windows.
 Package keychain stores the Starfleet client secret in the operating system's credential store: macOS Keychain, the Secret Service on Linux, Credential Manager on Windows.
metricfmt
Package metricfmt renders metric samples for text tables.
 Package metricfmt renders metric samples for text tables.
module
Package module defines the contract between the base pgedge CLI and its modules.
 Package module defines the contract between the base pgedge CLI and its modules.
output
reference
Package reference derives a module's reference pages from the files it embeds, and answers the routing questions `pgedge llms` and the generator ask of them.
 Package reference derives a module's reference pages from the files it embeds, and answers the routing questions `pgedge llms` and the generator ask of them.
selfupdate
Package selfupdate implements `pgedge self update`: resolving a release tag from a fetched release list, verifying the downloaded asset, and swapping it into place.
 Package selfupdate implements `pgedge self update`: resolving a release tag from a fetched release list, verifying the downloaded asset, and swapping it into place.
starfleet
Package cloud is the pgEdge Starfleet module: one product, one connection, three faces (account-level resources, byoc, managed).
 Package cloud is the pgEdge Starfleet module: one product, one connection, three faces (account-level resources, byoc, managed).
starfleet/account/api
Package api provides primitives to interact with the openapi HTTP API.
 Package api provides primitives to interact with the openapi HTTP API.
starfleet/account/cmd
Package cmd wires the account-level commands of the pgedge starfleet tree: authentication, API clients, tenants, invites and memberships — everything the accounts half of the Starfleet API owns.
 Package cmd wires the account-level commands of the pgedge starfleet tree: authentication, API clients, tenants, invites and memberships — everything the accounts half of the Starfleet API owns.
starfleet/byoc
Package byoc holds the byoc sub-tree of the starfleet module: its generated API client, its command tree and its reference pages.
 Package byoc holds the byoc sub-tree of the starfleet module: its generated API client, its command tree and its reference pages.
starfleet/byoc/api
Package api provides primitives to interact with the openapi HTTP API.
 Package api provides primitives to interact with the openapi HTTP API.
starfleet/byoc/cmd
Package cmd wires the pgEdge BYOC command tree: the module root, its persistent flags, and the authenticated API client shared by every resource command.
 Package cmd wires the pgEdge BYOC command tree: the module root, its persistent flags, and the authenticated API client shared by every resource command.
starfleet/cmd
Package cmd wires the pgedge starfleet command tree: the starfleet root, its persistent connection flags, the account-level commands (auth, doctor, tenant, client, invite, membership), and the byoc and managed sub-trees.
 Package cmd wires the pgedge starfleet command tree: the starfleet root, its persistent connection flags, the account-level commands (auth, doctor, tenant, client, invite, membership), and the byoc and managed sub-trees.
starfleet/conn
Package conn owns the single pgEdge Starfleet API connection: base-URL and credential precedence, the token exchange and cache, the shared HTTP client, and the exit codes every Starfleet module reports.
 Package conn owns the single pgEdge Starfleet API connection: base-URL and credential precedence, the token exchange and cache, the shared HTTP client, and the exit codes every Starfleet module reports.
starfleet/connstr
Package connstr assembles a libpq connection string from the parts a database GET returns, for the managed and byoc connection-string verbs.
 Package connstr assembles a libpq connection string from the parts a database GET returns, for the managed and byoc connection-string verbs.
starfleet/managed
Package managed holds the managed sub-tree of the starfleet module: its generated API client, its command tree and its reference pages.
 Package managed holds the managed sub-tree of the starfleet module: its generated API client, its command tree and its reference pages.
starfleet/managed/api
Package api provides primitives to interact with the openapi HTTP API.
 Package api provides primitives to interact with the openapi HTTP API.
starfleet/managed/cmd
Package cmd wires the pgEdge Managed command tree: the module root, its persistent flags, and the authenticated API client shared by every resource command.
 Package cmd wires the pgEdge Managed command tree: the module root, its persistent flags, and the authenticated API client shared by every resource command.
testsupport
Package testsupport holds the test fixtures every Starfleet module's command tree needs: an isolated Runtime, the stub token/resource server, and the authenticated-command runner.
 Package testsupport holds the test fixtures every Starfleet module's command tree needs: an isolated Runtime, the stub token/resource server, and the authenticated-command runner.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.