vybekiit 0.7.26 → 0.7.27

package/dist/global-skills/use-railway/references/iac.md

@@ -1,65 +1,62 @@
 # Configuration in source control
 
-Choose one configuration model before editing files. Never manage the same service with both models.
+Use Infrastructure as Code for project configuration. Keep one authoring file and never manage a service with both IaC and legacy Config as Code.
 
 ## Choose the model
 
-Prefer TypeScript Infrastructure as Code when the repository has TypeScript set up. Use `railway.json` only as the fallback for repositories without TypeScript.
+TypeScript IaC is generally available. Python and Go authoring are in beta. Preserve an existing `.railway/railway.ts`, `.railway/railway.py`, or `.railway/railway.go`; do not switch languages based on the app's `package.json`, `go.mod`, or framework. With no existing authoring file, `config init` and `config pull` default to TypeScript even for non-TypeScript apps. `config init` and `config pull` have no language flag: the CLI picks the language only from an existing authoring file. To honor an explicit Python/Go preference on a fresh project, create an empty `.railway/railway.py` or `.railway/railway.go` first, then run `config pull` so the import is emitted in that language. `config migrate --lang py|go` emits Python/Go only when translating legacy `railway.json`/`railway.toml`.
 
-Use TypeScript IaC when any of these signals exist in the current project or workspace:
-
-- `.railway/railway.ts` already exists.
-- A `tsconfig.json` or another `tsconfig*.json` exists.
-- `package.json` declares `typescript`, or the project contains `.ts` or `.tsx` source files.
-
-If none of those signals exist, create or edit `railway.json`. Do not choose `railway.toml` for new agent-authored configuration.
-
-If a TypeScript repository already has `railway.json`, migrate the intended settings to `.railway/railway.ts` and remove the old file before planning. If the user explicitly asks to preserve the existing model rather than migrate, edit the existing file and explain that it remains service-level Config as Code.
-
-The models have different scopes:
+`railway.json` and `railway.toml` are deprecated. New services cannot opt into Config as Code; existing files stop being read on **2026-12-01**. Do not create them as a fallback. For an existing legacy service, use the migration workflow below; if the user requests a temporary legacy edit, explain the cutoff and keep its current format.
 
 | Model | Scope | Applies when |
 |---|---|---|
-| `.railway/railway.ts` | Whole Railway project: services, databases, buckets, volumes, variables, replicas, domains, and canvas groups | `railway config apply` applies the reviewed project plan |
-| `railway.json` | One service's build and deploy settings | The next deployment reads the file; it does not update dashboard settings |
+| `.railway/railway.ts`, `.py`, or `.go` | Project/environment: services, databases, buckets, volumes, variables, replicas, domains, and canvas groups | `railway config apply` applies the project plan |
+| Existing `railway.json` / `railway.toml` | One legacy service's build and deploy settings | Read during deployments until the cutoff; overrides dashboard values for that deployment |
 
-## TypeScript Infrastructure as Code
+## Infrastructure as Code
 
-The desired Railway project state lives in:
+Keep exactly one of these files:
 
 ```text
 .railway/railway.ts
+.railway/railway.py
+.railway/railway.go
 ```
 
 `railway config init` and `railway config pull` also create `.railway/README.md`. Railway agent setup installs the shared `use-railway` skill; config commands do not need or create a project-local skill.
 
+Install the matching authoring package in the config's package environment: `npm install railway`, `pip install railway-sdk`, or `go get github.com/railwayapp/railway-go-sdk`. Python/Go imports can generate `.railway/requirements.txt` or `.railway/go.mod`; use those when present. CLI 5.42+ evaluates the graph natively, but still needs the language runtime and SDK to evaluate authoring code. `--runner` is an optional legacy TypeScript runner override, not a prerequisite.
+
 ### Core rules
 
 1. Express Railway product intent, not internal API details.
-2. Do not write Railway UUIDs into `.railway/railway.ts`.
+2. Do not write Railway UUIDs into the authoring file.
 3. Do not write `EnvironmentConfigPatch`, `ServiceInstance`, Backboard internals, or generated Railway domains into source.
 4. Prefer helpers such as `service()`, `postgres()`, `redis()`, `mysql()`, `mongo()`, `bucket()`, `volume()`, `group()`, `github()`, and `image()`.
 5. Use `service.env.VARIABLE` and `database.env.VARIABLE` for references.
-6. Keep secrets out of source. Imported unknown secret values should use `preserve()` or be omitted when the user wants a smaller import.
+6. Keep secrets out of source. Imports use `preserve()` by default for existing variables; omit them only when a smaller import is intended.
 7. Prefer product DSL names such as `domains`, `replicas`, and `group`; avoid internal names such as `customDomains` and `multiRegionConfig`.
 8. Do not add platform defaults unless the user explicitly wants them.
-9. After editing `.railway/railway.ts`, run `railway config plan`.
+9. After editing the authoring file, run `railway config plan`.
 10. Do not run `railway config apply` unless the user explicitly asks.
 11. Never use `railway config apply --yes` or `--confirm-destructive` from an agent session without explicit user approval for the exact plan.
 
 ### Initialize or import
 
 ```bash
-railway config init                         # create .railway/railway.ts
+railway config init                         # TypeScript by default; preserve existing language
 railway config init --force                 # overwrite existing generated files
 railway config pull                         # import the linked project
-railway config pull --force                 # overwrite existing .railway/railway.ts
+railway config pull --force                 # overwrite the existing authoring file
 railway config pull --omit-preserved-variables # omit unknown variable values
 railway config pull --json                  # print current graph instead of writing files
 railway config pull --agent                 # ask an agent to clean the import afterward
+railway config pull --include-variables     # decrypt and inline non-sealed values
 ```
 
-If the directory is not linked, the CLI prompts for project and environment in an interactive terminal. In agent workflows, link first or pass explicit project and environment context when supported.
+Use `--include-variables` only when writing those values to source is intended: it includes non-sealed secrets too. Sealed values remain `preserve()`. A normal import should produce a no-change plan; inspect any diff before applying.
+
+Plan/apply discover the nearest `.railway/railway.{ts,py,go}` by walking up from the current directory. `--file <path>` overrides that selection. Run init/pull/migrate from the intended project root. Config commands do not expose `--project`/`--environment` selectors: verify the link or use `railway link --project <id> --environment <env>` before noninteractive work. Interactive commands can prompt for missing context.
 
 ### Authoring
 
@@ -91,6 +88,7 @@ const db = postgres("postgres");
 const api = service("api", {
   source: github("owner/repo", { branch: "main" }),
   build: "pnpm build",
+  preDeploy: "pnpm db:migrate",
   start: "pnpm start",
   env: {
     DATABASE_URL: db.env.DATABASE_URL,
@@ -170,7 +168,20 @@ railway config apply --yes --confirm-destructive
 railway config apply --json --yes --confirm-destructive
 ```
 
-`apply` runs a fresh plan. If remote state changed, Railway rejects the stale apply and requires another plan. In non-interactive or agent sessions, destructive changes require `--confirm-destructive` in addition to `--yes` or `--json`; add it only after the user explicitly approves the exact destructive impact.
+Ordinary `apply` evaluates a fresh plan. Changes to the environment between planning inside that invocation and applying are rejected. In non-interactive or agent sessions, destructive changes require `--confirm-destructive` in addition to `--yes` or `--json`; add it only after the user explicitly approves the exact destructive impact.
+
+### Apply the reviewed plan in CI
+
+CLI 5.45.1+ can save the evaluated change set and apply that exact artifact:
+
+```bash
+railway config plan --out railway-plan.json
+railway config apply --plan railway-plan.json --yes
+```
+
+Review the first command's diff before authorizing the apply. Store the artifact outside `.railway/` because that directory's source tree is pinned. The artifact contains the change set, environment ID and config etag, and source tree identity. `apply --plan` does not reevaluate the authoring code; it rejects changed source or remote state rather than quietly generating another plan. Keep the same CLI version and source checkout between jobs. Use `--source-tree` on `plan` only when CI deliberately supplies the source identity. Treat plan artifacts as potentially secret-bearing even when terminal diffs are redacted.
+
+When a saved plan is stale, create and review a replacement. Destructive saved plans still require `--confirm-destructive`. For maintained CI integration, use [railwayapp/config](https://github.com/railwayapp/config).
 
 ### Review checklist
 
@@ -184,74 +195,52 @@ Before applying, confirm:
 - Scaling uses `replicas`, not `multiRegionConfig`.
 - No generated Railway service domains or Railway UUIDs are committed.
 
-### Troubleshoot TypeScript IaC
+### Troubleshoot IaC
 
-- **Service is already managed by `railway.json`**: migrate its intended settings and remove the old file before planning; Railway blocks dual ownership.
+- **Service is already managed by Config as Code**: use migration below; deleting the file alone does not clear its Railway Config File setting.
 - **Plan shows secrets as hidden**: expected. Use `--show-values` only with user approval.
 - **Apply says the plan is stale**: run a new plan, inspect it, then apply again only if requested.
 - **Destructive apply is blocked**: get explicit approval for the exact plan before adding `--confirm-destructive`.
-- **Imported variables use `preserve()`**: Railway could not safely print encrypted values; `preserve()` retains the remote value.
-- **Generated code is too literal**: simplify `.railway/railway.ts`, then run another plan.
+- **Imported variables use `preserve()`**: this is the default, including readable values; it retains the remote value without putting it into source.
+- **Missing Railway package**: install the SDK for the existing authoring language in its runtime environment; do not replace the config language to work around the error.
+- **Generated code is too literal**: simplify the authoring file, then run another plan.
 
-## `railway.json` fallback
+## Migrate legacy Config as Code
 
-Use this path only when the repository has no TypeScript setup. `railway.json` controls one service's build and deploy settings, not project resources such as databases, buckets, variables, or canvas groups.
+Use CLI **5.49.1 or newer**: its TypeScript migration and all-language pull fixes preserve `preDeployCommand` as the first-class `preDeploy` field. Earlier TypeScript migration output could silently omit a database migration command.
 
-Start with the schema so editors validate fields:
+Start with a dry-run from the repository root:
 
-```json
-{
-  "$schema": "https://railway.com/railway.schema.json",
-  "build": {
-    "builder": "RAILPACK",
-    "buildCommand": "npm run build"
-  },
-  "deploy": {
-    "preDeployCommand": ["npm run db:migrate"],
-    "startCommand": "npm start",
-    "healthcheckPath": "/health",
-    "healthcheckTimeout": 300,
-    "restartPolicyType": "ON_FAILURE",
-    "restartPolicyMaxRetries": 5
-  }
-}
+```bash
+railway config migrate
+railway config migrate --service api
+railway config migrate --lang py
+railway config migrate --lang go
 ```
 
-Rules for this fallback:
+The default emits proposed TypeScript without writing files or clearing remote settings. `--service` selects a service when multiple configs are found; with one file it can name the emitted service. Inspect the discovered paths and service mapping in a monorepo. Single-service migration may emit a named partial rather than claim the whole project; retain that ownership boundary when merging it into existing IaC.
 
-1. Include only settings the user intends to override. File values override dashboard values for that deployment.
-2. Use the canonical schema field names; do not copy internal environment patch names blindly.
-3. Keep service variables and secrets out of `railway.json`; manage them with Railway variables.
-4. Use `environments.<name>` for environment-specific overrides and `environments.pr` for PR environments.
-5. In a monorepo, place the file at the service root or set the service's custom Railway config file path to its absolute repository path.
-6. Validate the JSON after editing. A deployment is required for the config to take effect; editing the file does not mutate dashboard settings.
+In v5.49.1, Python/Go **migration** emits only build/start commands and the healthcheck path. Manually carry over other intended settings, including pre-deploy commands, replicas, and healthcheck timeouts, before applying the resulting IaC. A successful migration command is not proof of a lossless translation in any language; compare the original files and plan.
 
-Example environment override:
+For an authorized migration, write the result and clear the discovered services' Railway Config File settings:
 
-```json
-{
-  "$schema": "https://railway.com/railway.schema.json",
-  "deploy": {
-    "startCommand": "npm start"
-  },
-  "environments": {
-    "staging": {
-      "deploy": {
-        "startCommand": "npm run staging"
-      }
-    },
-    "pr": {
-      "deploy": {
-        "startCommand": "npm run preview"
-      }
-    }
-  }
-}
+```bash
+railway config migrate --apply
+railway config migrate --apply --delete-files
 ```
 
-For the complete field list, use the live JSON schema or Railway's Config as Code reference rather than guessing unsupported keys.
+`--apply` here writes source and changes remote config-file settings; it does **not** apply the resulting IaC project plan. `--delete-files` additionally removes discovered legacy files and requires `--apply`. If an authoring file already exists, merge the dry-run output into it instead of using `--force` to overwrite unrelated resources. Preserve the language with `--lang` when needed; migration defaults to `ts`.
+
+Before completing the migration:
+
+- Compare build/start/pre-deploy commands, health checks, regions/replicas, and environment overrides with the original files. Do not assume every legacy field was translated.
+- Preserve secrets and review the service identities and ownership scope.
+- Run `railway config plan`; inspect unexpected removals or changes, then apply only within the user's authorized scope.
+- Check for remaining legacy files and custom Railway Config File paths so deployments do not retain dual ownership.
+
+For a requested temporary edit to an existing legacy service, retain its format, validate against the [Config as Code reference](https://docs.railway.com/config-as-code/reference), and explain the 2026-12-01 cutoff. Config as Code has deployment-time precedence over dashboard settings; a deployment is needed for edits to take effect. Keep variables and secrets in Railway variables.
 
 ## Validated against
 
-- Docs: [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code), [IaC reference](https://docs.railway.com/infrastructure-as-code/reference), [Config as Code](https://docs.railway.com/guides/config-as-code), [Config as Code reference](https://docs.railway.com/reference/config-as-code)
-- CLI source: [config/mod.rs](https://github.com/railwayapp/cli/blob/v5.27.1/src/commands/config/mod.rs), [config/runner.rs](https://github.com/railwayapp/cli/blob/v5.27.1/src/commands/config/runner.rs)
+- Docs: [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code), [IaC reference](https://docs.railway.com/infrastructure-as-code/reference), [Config as Code](https://docs.railway.com/config-as-code)
+- CLI source (v5.49.1): [config/mod.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/config/mod.rs), [config/migrate.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/config/migrate.rs), [authoring.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/config/authoring.rs), [eval.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/iac/eval.rs), [saved_plan.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/iac/saved_plan.rs)

package/dist/global-skills/use-railway/references/operate.md

@@ -79,7 +79,7 @@ HTTP filter fields include `@method`, `@path`, `@host`, `@requestId`, `@srcIp`,
 
 ### Network flow logs
 
-Use network flow logs for private networking, TCP proxy, outbound allowlist, DNS, or dropped-packet investigations:
+Use network flow logs for private networking, TCP proxy, outbound allowlist, or dropped-packet investigations. Use DNS query logs below for resolution results:
 
 ```bash
 railway logs --service <service> --network --lines 100 --json
@@ -104,6 +104,20 @@ Useful filters:
 | `--src`, `--dst`, `--host` | IP filters |
 | `--drop-cause <cause>` | Drop reason |
 
+### DNS query logs
+
+CLI 5.29+ exposes DNS resolution results directly:
+
+```bash
+railway logs --service <service> --environment <env> --dns --lines 100 --json
+railway logs --service <service> --dns --status failed --since 1h --lines 100 --json
+railway logs --service <service> --dns --rcode NXDOMAIN --lines 100 --json
+railway logs --service <service> --dns --qname backend.railway.internal --zone internal --lines 50 --json
+railway logs --service <service> --dns --domain example.com --qtype AAAA --lines 100 --json
+```
+
+Use `--qname` for the full query name, `--domain` for domain filtering, `--qtype` for record type, `--rcode` for DNS response code, and `--zone internal|external` for lookup scope. `--status failed` finds failed resolutions. DNS logs are service-level and mutually exclusive with build, deployment, HTTP, and network modes; do not pass a deployment ID or `--latest`. Correlate failed lookups with runtime errors and network flows instead of treating a DNS failure as an application crash.
+
 ## Metrics
 
 Use `railway metrics` for resource and HTTP metrics. It summarizes CPU, memory, network, volume, and HTTP data for the linked service by default.
@@ -125,6 +139,8 @@ Metric flags can be combined: `--cpu`, `--memory`, `--network`, `--volume`, and
 
 For custom grouping or measurements the CLI doesn't expose, use the GraphQL fallback in [request.md](request.md).
 
+For latency or errors that span several services, or a request a user reported with an `x-railway-trace-id` header, use tracing instead of correlating logs by hand: see [tracing.md](tracing.md).
+
 ## SSH
 
 Use SSH when logs and metrics don't expose enough state and the user needs shell-level inspection inside a running service.
@@ -156,6 +172,8 @@ For database-level metrics and introspection, use the analysis scripts. `railway
 - Redis, MySQL, and MongoDB introspection
 - Combined analysis via `scripts/analyze-<type>.py` (postgres, mysql, redis, mongo)
 
+For native PITR/HA/PgBouncer status and operations, use [databases.md](databases.md). For billed usage and spending limits, use [usage.md](usage.md); infrastructure metrics are not a billing statement.
+
 ## Failure triage
 
 When something is broken, classify the failure first. The fix depends on the class.
@@ -259,6 +277,10 @@ Always verify after fixing. Don't assume the redeploy succeeded.
 
 ## Troubleshoot common blockers
 
+- **`OAUTH_INSUFFICIENT_GRANT` / resource access denied**: CLI 5.37.4+ distinguishes a live OAuth session without access from an expired login. Check the resource IDs, workspace membership, and integration grant scope; repeating the same login may retain the same insufficient grant. Reauthorize with the necessary access only when the user intends that scope.
+- **Expired or invalid credentials**: follow the CLI's login/token-specific error. Transient refresh failures are not proof that access was revoked. Newer CLI versions refresh long-lived clients too; upgrade an old CLI before repeatedly reinstalling MCP to address stale authentication.
+- **CI log stream failed**: on CLI 5.41+, the command falls back to status polling. Inspect the submitted deployment before retrying; a logging error alone is not a deployment failure.
+
 - **Unlinked context**: `railway link --project <id-or-name>`
 - **Missing service scope for logs**: pass `--service` and `--environment` explicitly
 - **Wrong project in status or deploy polling**: pass `--project`, `--environment`, and `--service`; URL IDs beat local linked context
@@ -269,5 +291,6 @@ Always verify after fixing. Don't assume the redeploy succeeded.
 
 ## Validated against
 
-- Docs: [status.md](https://docs.railway.com/cli/status), [service.md](https://docs.railway.com/cli/service), [logs.md](https://docs.railway.com/cli/logs), [metrics.md](https://docs.railway.com/cli/metrics), [ssh.md](https://docs.railway.com/cli/ssh), [cdn.md](https://docs.railway.com/cli/cdn), [waf.md](https://docs.railway.com/cli/waf), [observability/logs.md](https://docs.railway.com/observability/logs), [observability/metrics.md](https://docs.railway.com/observability/metrics)
-- CLI source: [status.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/status.rs), [service.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/service.rs), [logs.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/logs.rs), [metrics.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/metrics.rs), [ssh/mod.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/ssh/mod.rs), [deployment.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/deployment.rs), [redeploy.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/redeploy.rs), [cdn.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/cdn.rs), [waf.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/waf.rs)
+- Docs: [status.md](https://docs.railway.com/cli/status), [service.md](https://docs.railway.com/cli/service), [logs.md](https://docs.railway.com/cli/logs), [metrics.md](https://docs.railway.com/cli/metrics), [ssh.md](https://docs.railway.com/cli/ssh), [cdn.md](https://docs.railway.com/cli/cdn), [waf.md](https://docs.railway.com/cli/waf), [observability/logs.md](https://docs.railway.com/observability/logs), [observability/metrics.md](https://docs.railway.com/observability/metrics), [observability/tracing.md](https://docs.railway.com/observability/tracing)
+- CLI source: [status.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/status.rs), [service.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/service.rs), [logs.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/logs.rs), [metrics.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/metrics.rs), [ssh/mod.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/ssh/mod.rs), [deployment.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/deployment.rs), [redeploy.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/redeploy.rs), [cdn.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/cdn.rs), [waf.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/waf.rs)
+- Authentication and CI recovery (v5.49.1): [client.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/client.rs), [up.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/up.rs)

package/dist/global-skills/use-railway/references/request.md

@@ -1,6 +1,6 @@
 # Request
 
-Official documentation and community endpoints. GraphQL operations for things the CLI doesn't expose.
+Official documentation and community endpoints. GraphQL operations without a dedicated CLI command or MCP tool.
 
 ## Official documentation
 
@@ -83,28 +83,36 @@ Thread URLs follow the format: `https://station.railway.com/{topic_slug}/{thread
 Community threads are anecdotal. Always pair with official docs when the answer informs an operational decision.
 
 
-## GraphQL helper
+## GraphQL with the CLI
 
-All GraphQL operations use the API helper script, which handles authentication automatically:
+Use `railway api` (CLI 5.28+) for API operations that dedicated commands and MCP tools cannot express. It uses the CLI's configured authentication and supports normal token refresh. Inspect the live schema before guessing fields or input shapes:
 
 ```bash
-scripts/railway-api.sh '<query>' '<variables-json>'
+railway api search projectUpdate --kind mutation
+railway api describe ProjectUpdateInput
+railway api describe Mutation.projectUpdate
+railway api schema --compact
+railway api '<query>' --variables '{"id":"<resource-id>"}'
+railway api --file query.graphql --variables @variables.json
+railway api --file query.graphql --raw-var id=<resource-id> --var enabled=true
 ```
 
-The script reads the API token from `~/.railway/config.json` and sends requests to `https://backboard.railway.com/graphql/v2`.
+`--var` parses JSON values when possible; `--raw-var` keeps strings. Queries can also come from stdin, with variables provided separately. Use `--operation-name` for documents containing multiple operations. Output is JSON by default; `--compact` changes formatting and there is no `--json` flag. HTTP errors and GraphQL `errors` fail the command; do not add `--allow-errors` when deciding whether a mutation succeeded. Query resource state before retrying an uncertain mutation.
+
+For an older CLI that cannot be upgraded, the bundled `scripts/railway-api.sh '<query>' '<variables-json>'` remains a compatibility fallback. The database analysis scripts (`dal.py`, `analyze-postgres.py`) still call this helper directly, so it must stay in the plugin even when agents use `railway api`. It reads `user.token` from `~/.railway/config.json`; it does not implement the CLI's environment-token selection or OAuth refresh. It expects query first and variables second, not a query on stdin, and callers must inspect its response for GraphQL errors. Keep the skill telemetry prefix on `railway api` calls just like other CLI calls.
 
 For the full API schema, see: https://docs.railway.com/api/llms-docs.md
 
 ## Project mutations
 
-The CLI doesn't expose project setting updates (rename, PR deploys, visibility). Use GraphQL:
+There is no dedicated project command for these setting updates (rename, PR deploys, visibility). Use GraphQL:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'mutation updateProject($id: String!, $input: ProjectUpdateInput!) {
     projectUpdate(id: $id, input: $input) { id name isPublic prDeploys botPrEnvironments }
   }' \
-  '{"id":"<project-id>","input":{"name":"new-name","prDeploys":true}}'
+  --variables '{"id":"<project-id>","input":{"name":"new-name","prDeploys":true}}'
 ```
 
 Common `ProjectUpdateInput` fields: `name`, `isPublic`, `prDeploys`, `botPrEnvironments`.
@@ -112,14 +120,14 @@ Common `ProjectUpdateInput` fields: `name`, `isPublic`, `prDeploys`, `botPrEnvir
 
 ## Service mutations
 
-The CLI can create services (`railway add`) but cannot rename them or change icons. Use GraphQL:
+Use `railway add` to create services and GraphQL to rename them or change icons:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
     serviceUpdate(id: $id, input: $input) { id name icon }
   }' \
-  '{"id":"<service-id>","input":{"name":"new-name"}}'
+  --variables '{"id":"<service-id>","input":{"name":"new-name"}}'
 ```
 
 `ServiceUpdateInput` fields: `name`, `icon` (image URL, animated GIF, or devicons URL like `https://devicons.railway.app/postgres`).
@@ -132,11 +140,11 @@ Get the service ID from `railway service list --json`.
 Prefer `railway add` for most cases. Use GraphQL for programmatic or advanced use:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'mutation createService($input: ServiceCreateInput!) {
     serviceCreate(input: $input) { id name }
   }' \
-  '{"input":{"projectId":"<project-id>","name":"my-service","source":{"image":"nginx:latest"}}}'
+  --variables '{"input":{"projectId":"<project-id>","name":"my-service","source":{"image":"nginx:latest"}}}'
 ```
 
 `ServiceCreateInput` fields:
@@ -158,13 +166,13 @@ After creating a service via GraphQL, configure it with a JSON config patch incl
 Use `railway metrics` for routine metric checks. Use GraphQL only when you need custom measurements, grouping, sample rates, or averaging windows that the CLI doesn't expose.
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query metrics($environmentId: String!, $serviceId: String, $startDate: DateTime!, $endDate: DateTime, $sampleRateSeconds: Int, $averagingWindowSeconds: Int, $groupBy: [MetricTag!], $measurements: [MetricMeasurement!]!) {
     metrics(environmentId: $environmentId, serviceId: $serviceId, startDate: $startDate, endDate: $endDate, sampleRateSeconds: $sampleRateSeconds, averagingWindowSeconds: $averagingWindowSeconds, groupBy: $groupBy, measurements: $measurements) {
       measurement tags { serviceId deploymentId region } values { ts value }
     }
   }' \
-  '{"environmentId":"<env-id>","serviceId":"<service-id>","startDate":"2026-02-19T00:00:00Z","measurements":["CPU_USAGE","MEMORY_USAGE_GB"]}'
+  --variables '{"environmentId":"<env-id>","serviceId":"<service-id>","startDate":"2026-02-19T00:00:00Z","measurements":["CPU_USAGE","MEMORY_USAGE_GB"]}'
 ```
 
 Available `MetricMeasurement` values: `CPU_USAGE`, `CPU_LIMIT`, `MEMORY_USAGE_GB`, `MEMORY_LIMIT_GB`, `NETWORK_RX_GB`, `NETWORK_TX_GB`, `DISK_USAGE_GB`, `EPHEMERAL_DISK_USAGE_GB`, `BACKUP_USAGE_GB`.
@@ -190,13 +198,13 @@ The CLI search command doesn't require authentication and supports pagination wi
 Use GraphQL only when the CLI output isn't enough for the workflow:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query templates($query: String!, $verified: Boolean, $recommended: Boolean) {
     templates(query: $query, verified: $verified, recommended: $recommended) {
       edges { node { code name description category } }
     }
   }' \
-  '{"query":"redis","verified":true}'
+  --variables '{"query":"redis","verified":true}'
 ```
 
 | Parameter | Type | Description |
@@ -230,21 +238,21 @@ For deploying into a specific environment or tracking the workflow, use the two-
 **Step 1**: Fetch the template config:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'query template($code: String!) {
     template(code: $code) { id serializedConfig }
   }' \
-  '{"code":"postgres"}'
+  --variables '{"code":"postgres"}'
 ```
 
 **Step 2**: Deploy with `templateDeployV2`:
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'mutation deploy($input: TemplateDeployV2Input!) {
     templateDeployV2(input: $input) { projectId workflowId }
   }' \
-  '{"input":{
+  --variables '{"input":{
     "templateId":"<id-from-step-1>",
     "serializedConfig":<config-object-from-step-1>,
     "projectId":"<project-id>",
@@ -253,10 +261,10 @@ scripts/railway-api.sh \
   }}'
 ```
 
-`serializedConfig` is the raw JSON object from the template query, not a string. Get `workspaceId` via `scripts/railway-api.sh 'query { project(id: "<project-id>") { workspaceId } }' '{}'`.
+`serializedConfig` is the raw JSON object from the template query, not a string. Get `workspaceId` via `railway api 'query { project(id: "<project-id>") { workspaceId } }'`.
 
 
 ## Validated against
 
 - Docs: [api docs](https://docs.railway.com/api/llms-docs.md), [agents.md](https://docs.railway.com/agents), [community.md](https://docs.railway.com/community), [cli/docs.md](https://docs.railway.com/cli/docs), [templates.md](https://docs.railway.com/cli/templates), [metrics.md](https://docs.railway.com/cli/metrics)
-- CLI source: [docs.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/docs.rs), [templates.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/templates.rs), [metrics.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/metrics.rs)
+- CLI source: [api.rs (v5.49.1)](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/api.rs), [client.rs (v5.49.1)](https://github.com/railwayapp/cli/blob/v5.49.1/src/client.rs), [docs.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/docs.rs), [templates.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/templates.rs), [metrics.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/metrics.rs)

package/dist/global-skills/use-railway/references/setup.md

@@ -59,14 +59,14 @@ railway init --name <project-name> --workspace <workspace-id-or-name>
 
 ### Update project settings
 
-Settings like project name, PR deploys, and visibility aren't exposed through the CLI. Use the GraphQL API helper (see [request.md](request.md)):
+Settings like project name, PR deploys, and visibility have no dedicated CLI command. Use `railway api` (see [request.md](request.md)):
 
 ```bash
-scripts/railway-api.sh \
+railway api \
   'mutation updateProject($id: String!, $input: ProjectUpdateInput!) {
     projectUpdate(id: $id, input: $input) { id name isPublic prDeploys }
   }' \
-  '{"id":"<project-id>","input":{"name":"new-name","prDeploys":true}}'
+  --variables '{"id":"<project-id>","input":{"name":"new-name","prDeploys":true}}'
 ```
 
 ## Services
@@ -140,7 +140,17 @@ railway connect <database-service> --ssh
 railway connect <database-service> --no-ssh
 ```
 
-The local database client must be installed. By default, `connect` uses a public TCP proxy when one exists and falls back to an SSH tunnel when no public proxy URL is available. Use `--ssh` to force the tunnel path, or `--no-ssh` to require a public TCP proxy.
+The local database client must be installed for a shell. By default, `connect` uses a public TCP proxy when one exists and falls back to an SSH tunnel when no public proxy URL is available. Use `--ssh` to force the tunnel path, or `--no-ssh` to require a public TCP proxy.
+
+For TablePlus, DBeaver, pgAdmin, or another GUI, CLI 5.27+ can hold a private tunnel open without starting or requiring a local database CLI:
+
+```bash
+railway connect <database-service> --tunnel-only --port 15432 --project <project-id> --environment production
+```
+
+`--tunnel-only` implies SSH and conflicts with `--no-ssh`. Omit `--port` to choose an available ephemeral port. Use the printed local connection details in the GUI; they include credentials, so do not echo them into a report. Keep the process running while the GUI is connected and stop it when finished. With `--project`, always supply `--environment`.
+
+For backups, PITR, HA conversion/scaling, or connection pooling, load [databases.md](databases.md).
 
 ### Delete a service
 
@@ -361,4 +371,5 @@ When creating projects, Railway uses the default workspace unless `--workspace`
 ## Validated against
 
 - Docs: [cli.md](https://docs.railway.com/cli), [init.md](https://docs.railway.com/cli/init), [add.md](https://docs.railway.com/cli/add), [link.md](https://docs.railway.com/cli/link), [project.md](https://docs.railway.com/cli/project), [service.md](https://docs.railway.com/cli/service), [connect.md](https://docs.railway.com/cli/connect), [templates.md](https://docs.railway.com/cli/templates), [list.md](https://docs.railway.com/cli/list), [whoami.md](https://docs.railway.com/cli/whoami)
-- CLI source: [init.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/init.rs), [add.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/add.rs), [project.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/project.rs), [service.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/service.rs), [connect.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/connect.rs), [templates.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/templates.rs), [list.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/list.rs), [bucket.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/bucket.rs)
+- CLI source: [init.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/init.rs), [add.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/add.rs), [project.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/project.rs), [service.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/service.rs), [connect.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/connect.rs), [templates.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/templates.rs), [list.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/list.rs), [bucket.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/bucket.rs)
+- API command: [api.rs (v5.49.1)](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/api.rs)