vybekiit 0.4.0 → 0.6.0

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

@@ -0,0 +1,108 @@
+# Infrastructure as Code
+
+Define, import, preview, and apply a Railway project from `.railway/railway.ts`.
+
+Use Railway IaC when the user wants project-level configuration in source control: services, databases, buckets, volumes, variables, replicas, domains, and canvas groups. Do not use it for a single-service deploy setting that is already owned by `railway.json` or `railway.toml`; migrate that service first so there is only one source of truth.
+
+## Files
+
+Railway IaC uses TypeScript:
+
+```text
+.railway/railway.ts
+.railway/README.md
+.agents/skills/railway-config/SKILL.md
+```
+
+`railway config init` and `railway config pull` create the support files when missing. The project-local `railway-config` skill helps future agents edit `.railway/railway.ts` safely.
+
+## Initialize or import
+
+```bash
+railway config init                         # create a starter .railway/railway.ts
+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 --json                  # print current graph instead of writing files
+railway config pull --agent                 # ask an agent to clean the import afterward
+```
+
+If the directory is not linked, the CLI prompts for project/environment in an interactive terminal. In agent workflows, prefer linking first or passing explicit project/environment context when the CLI supports it.
+
+## Plan
+
+Always plan before applying:
+
+```bash
+railway config plan
+railway config plan --json
+railway config plan --verbose
+railway config plan --show-values
+railway config plan --detailed-exit-code
+```
+
+Plan output summarizes changes in Terraform style:
+
+```text
+Plan: 1 to add, 0 to change, 0 to destroy
+```
+
+Variable values are redacted by default. Use `--show-values` only when the user is intentionally reviewing non-secret config or accepts the secret exposure risk. Use `--detailed-exit-code` for CI drift checks: exit `0` means no changes, exit `2` means changes are pending, and other non-zero exits are errors.
+
+## Apply
+
+```bash
+railway config apply
+railway config apply --yes
+railway config apply --yes --confirm-destructive
+railway config apply --json --yes --confirm-destructive
+```
+
+`apply` always runs a fresh plan first. If the environment changed after the last plan, Railway rejects the apply and asks for a new plan. In non-interactive or agent sessions, destructive changes require `--confirm-destructive` in addition to `--yes` or `--json`; do not add it unless the user explicitly approved the destructive impact.
+
+## Authoring pattern
+
+Keep `.railway/railway.ts` readable and explicit:
+
+```ts
+import { defineRailway, project, service } from "railway/iac";
+
+export default defineRailway(() => {
+  const web = service("web", {
+    build: "pnpm build",
+    start: "pnpm start",
+  });
+
+  return project("my-project", {
+    resources: [web],
+  });
+});
+```
+
+Use imported helpers when needed: `service`, `postgres`, `redis`, `mysql`, `mongo`, `bucket`, `volume`, `group`, `github`, `image`, and `preserve`.
+
+## Migration from config as code
+
+When a service has `railway.json` or `railway.toml`:
+
+1. Run `railway config pull --force`.
+2. Translate only the intended service settings into `.railway/railway.ts`.
+3. Remove the old service-level config file or clear its custom config file path.
+4. Run `railway config plan`.
+5. Apply only when the plan matches the intended migration.
+
+If the plan shows unexpected service deletes, variable deletes, bucket deletes, or unrelated changes, stop and inspect the generated file before applying.
+
+## Troubleshoot IaC
+
+- **Service is already managed by `railway.json` or `railway.toml`**: migrate that service first; Railway blocks dual ownership.
+- **Plan shows secrets as hidden**: this is expected. Use `--show-values` only with user approval.
+- **Apply says the plan is stale**: run `railway config plan` again, inspect the new diff, then re-apply.
+- **Destructive apply blocked**: get explicit user approval and rerun with `--confirm-destructive`.
+- **Imported variables use `preserve()`**: Railway could not safely print encrypted secret values; preserve keeps the remote value.
+- **Generated code is too literal**: edit `.railway/railway.ts` into a cleaner shape, then verify with `railway config plan`.
+
+## Validated against
+
+- Docs: [infrastructure-as-code.md](https://docs.railway.com/infrastructure-as-code), [infrastructure-as-code/reference.md](https://docs.railway.com/infrastructure-as-code/reference)
+- CLI source: [config/mod.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/config/mod.rs), [config/runner.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/config/runner.rs)

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

@@ -0,0 +1,273 @@
+# Operate
+
+Check health, read logs, query metrics, and troubleshoot failures.
+
+## Health snapshot
+
+Start broad, then narrow:
+
+```bash
+railway status --json                                    # linked context
+railway status --project <project> --environment <env> --json
+railway service list --json                              # services in current environment
+railway deployment list --limit 10 --json                # recent deployments
+railway deployment list --project <project> --environment <env> --service <service> --limit 10 --json
+```
+
+Use explicit `--project`, `--environment`, and `--service` when the user provided a URL or when the current directory may be linked to a different project.
+
+Deployment statuses include `SUCCESS`, `QUEUED`, `INITIALIZING`, `WAITING`, `BUILDING`, `DEPLOYING`, `NEEDS_APPROVAL`, `FAILED`, `CRASHED`, `SLEEPING`, `SKIPPED`, `REMOVING`, and `REMOVED`.
+
+For projects with buckets, include bucket status:
+
+```bash
+railway bucket list --json                                       # buckets in current environment
+railway bucket info --bucket <name> --json                       # storage size, object count, region
+```
+
+If everything looks healthy, return a summary and stop. If something is degraded or failing, continue to log inspection.
+
+## Logs
+
+### Recent logs
+
+```bash
+railway logs --service <service> --lines 200 --json              # runtime logs
+railway logs --service <service> --build --lines 200 --json      # build logs
+railway logs --latest --lines 200 --json                         # latest deployment
+```
+
+In an interactive terminal, `railway logs` streams indefinitely when no bounding flags are given. Always use `--lines`, `--since`, or `--until` to get a bounded fetch for agent workflows.
+
+### Time-bounded queries
+
+```bash
+railway logs --service <service> --since 1h --lines 400 --json
+railway logs --service <service> --since 30m --until 10m --lines 400 --json
+```
+
+### Filtered queries
+
+Use `--filter` to narrow logs without scanning everything manually:
+
+```bash
+railway logs --service <service> --lines 200 --filter "@level:error" --json
+railway logs --service <service> --lines 200 --filter "@level:warn AND timeout" --json
+railway logs --service <service> --lines 200 --filter "connection refused" --json
+```
+
+Filter syntax supports text search (`"error message"`), attribute filters (`@level:error`, `@level:warn`), and boolean operators (`AND`, `OR`, `-` for negation). Full syntax: https://docs.railway.com/cli/logs
+
+### Scoped by environment
+
+```bash
+railway logs --service <service> --environment <env> --lines 200 --json
+```
+
+### HTTP logs
+
+Use HTTP logs when a service responds with errors, latency spikes, or routing problems:
+
+```bash
+railway logs --service <service> --http --status ">=400" --lines 100 --json
+railway logs --service <service> --http --method POST --path /api/users --lines 100 --json
+railway logs --service <service> --http --request-id <request-id> --lines 20 --json
+railway logs --service <service> --http --filter "@totalDuration:>=1000" --lines 100 --json
+```
+
+HTTP filter fields include `@method`, `@path`, `@host`, `@requestId`, `@srcIp`, `@edgeRegion`, `@httpStatus`, `@totalDuration`, `@responseTime`, `@txBytes`, and `@rxBytes`.
+
+### Network flow logs
+
+Use network flow logs for private networking, TCP proxy, outbound allowlist, DNS, or dropped-packet investigations:
+
+```bash
+railway logs --service <service> --network --lines 100 --json
+railway logs --service <service> --network --direction egress --protocol tcp --lines 100 --json
+railway logs --service <service> --network --peer postgres --port 5432 --lines 100 --json
+railway logs --service <service> --network --status dropped --lines 100 --json
+railway logs --service <service> --network --filter "@peer_kind:internet @port:443" --lines 100 --json
+```
+
+Network flow logs are service-level, not deployment-level. Do not pass a deployment ID or `--latest` with `--network`.
+
+Useful filters:
+
+| Flag | Use for |
+|---|---|
+| `--protocol tcp|udp|icmp|icmpv6|unknown` | Layer 4 protocol |
+| `--direction ingress|egress` | Traffic direction |
+| `--peer <service|internet|dns|edge-proxy>` | Named peer or well-known peer |
+| `--peer-kind service|internet|edge_proxy|local_dns|unknown` | Peer class |
+| `--status ok|dropped` / `--dropped true` | Dropped traffic |
+| `--port <port>` | Source or destination port |
+| `--src`, `--dst`, `--host` | IP filters |
+| `--drop-cause <cause>` | Drop reason |
+
+## Metrics
+
+Use `railway metrics` for resource and HTTP metrics. It summarizes CPU, memory, network, volume, and HTTP data for the linked service by default.
+
+```bash
+railway metrics --service <service> --since 1h --json
+railway metrics --service <service> --since 6h --cpu --memory --json
+railway metrics --service <service> --http --method POST --path /api/users --json
+railway metrics --all --environment production --json
+```
+
+Use `--raw` for time-series data points:
+
+```bash
+railway metrics --service <service> --raw --cpu --json
+```
+
+Metric flags can be combined: `--cpu`, `--memory`, `--network`, `--volume`, and `--http`. Use `--watch` only in an interactive terminal; it opens a live TUI and conflicts with `--json` and `--raw`.
+
+For custom grouping or measurements the CLI doesn't expose, use the GraphQL fallback in [request.md](request.md).
+
+## SSH
+
+Use SSH when logs and metrics don't expose enough state and the user needs shell-level inspection inside a running service.
+
+```bash
+railway ssh --service <service> --environment <env>
+railway ssh --service <service> --environment <env> -- "printenv | sort"
+railway ssh --service <service> --environment <env> --session railway-debug
+railway ssh --service <service> --environment <env> --identity-file ~/.ssh/id_ed25519_railway
+```
+
+Manage Railway SSH keys with:
+
+```bash
+railway ssh keys list
+railway ssh keys add --key ~/.ssh/id_ed25519.pub --name <key-name>
+railway ssh keys github
+railway ssh keys remove <key-id> --2fa-code <code>
+```
+
+Workspace-owned keys use `--workspace <workspace-id>` and require workspace Admin access. SSH key management doesn't work with project tokens (`RAILWAY_TOKEN`); use `railway login` or a workspace-scoped `RAILWAY_API_TOKEN`.
+
+## Database inspection
+
+For database-level metrics and introspection, use the analysis scripts. `railway metrics` can provide infrastructure metrics and supported database summaries, while the scripts provide deeper engine-level analysis. See [analyze-db.md](analyze-db.md) for comprehensive database analysis including:
+
+- Deep Postgres analysis (pg_stat_statements, vacuum health, index health, cache hit ratios)
+- HA cluster checks (Patroni, etcd, HAProxy)
+- Redis, MySQL, and MongoDB introspection
+- Combined analysis via `scripts/analyze-<type>.py` (postgres, mysql, redis, mongo)
+
+## Failure triage
+
+When something is broken, classify the failure first. The fix depends on the class.
+
+### Build failures
+
+The service failed to build. Look at build logs:
+
+```bash
+railway logs --latest --build --lines 400 --json
+```
+
+Common causes and fixes:
+- **Missing dependencies**: check lockfiles, verify package manager detection
+- **Wrong build command**: override with `railway environment edit --service-config <service> build.buildCommand "<command>"`
+- **Builder mismatch**: switch builders with `railway environment edit --service-config <service> build.builder RAILPACK`
+- **Wrong root directory** (monorepo): set `source.rootDirectory` to the correct package path
+
+### Runtime failures
+
+The build succeeded but the service crashes or misbehaves:
+
+```bash
+railway logs --latest --lines 400 --json
+railway logs --service <service> --since 1h --lines 400 --json
+```
+
+Common causes and fixes:
+- **Bad start command**: override with `railway environment edit --service-config <service> deploy.startCommand "<command>"`
+- **Missing runtime variable**: check `railway variable list --service <service> --json` and set missing values
+- **Port mismatch**: the service must listen on `$PORT` (Railway injects this). Verify with logs.
+- **Upstream dependency down**: check other services' status and logs
+
+### Config-driven failures
+
+Something worked before and broke after a config change:
+
+```bash
+railway environment config --json
+railway variable list --service <service> --json
+```
+
+Compare the config against expected values. Look for changes that may have introduced the regression.
+
+### Networking failures
+
+Domain returns errors, or service-to-service calls fail:
+
+```bash
+railway domain list --service <service> --json
+railway domain status <domain> --service <service> --json
+railway private-network status --service <service> --json
+railway tcp-proxy list --service <service> --json
+railway outbound-network status --service <service> --json
+railway logs --service <service> --http --status ">=400" --lines 100 --json
+railway logs --service <service> --network --status dropped --lines 100 --json
+```
+
+Check: target port matches what the service listens on, domain status is healthy, private domain variable references are correct, TCP proxy status is active, and outbound networking changes have been followed by the required redeploy.
+
+### CDN and WAF incidents
+
+For cache behavior, inspect both CLI settings and response headers:
+
+```bash
+railway cdn status --service <service> --json
+railway logs --service <service> --http --status ">=400" --lines 100 --json
+curl -I https://<domain>/<path>
+curl https://<domain>/.railway/cdn-trace?json
+```
+
+`x-cache: HIT` means the request did not reach the service. `DYNAMIC` means the edge reached the service but did not cache the response. Check method, `Authorization`, `Set-Cookie`, `Cache-Control`, `Vary`, response size, and HTML caching mode.
+
+For active traffic floods or unexpected `429` responses:
+
+```bash
+railway waf under-attack status --service <service> --json
+railway logs --service <service> --http --status 429 --lines 100 --json
+```
+
+Under Attack Mode can block API clients and webhooks. If the service is API-only, disabling WAF may be the correct recovery after confirming with the user.
+
+## Recovery
+
+After identifying the cause, fix and verify:
+
+```bash
+# Fix (examples)
+railway environment edit --service-config <service> deploy.startCommand "<correct-command>"
+railway variable set MISSING_VAR=value --service <service>
+
+# Redeploy
+railway redeploy --service <service> --yes
+
+# Verify
+railway deployment list --service <service> --limit 5 --json
+railway logs --service <service> --lines 200 --json
+```
+
+Always verify after fixing. Don't assume the redeploy succeeded.
+
+## Troubleshoot common blockers
+
+- **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
+- **No deployments found**: the service exists but has never deployed, create an initial deploy first
+- **Metrics return empty**: check the time window, service scope, and whether the service has active deployments
+- **Config patch type error**: check the typed paths in [configure.md](configure.md), for example, `numReplicas` is an integer, not a string
+- **No network flow logs**: confirm the time window and service scope; network logs are not tied to deployment IDs
+
+## 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)

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

@@ -0,0 +1,262 @@
+# Request
+
+Official documentation and community endpoints. GraphQL operations for things the CLI doesn't expose.
+
+## Official documentation
+
+Primary sources for authoritative Railway information:
+
+- **Full LLM docs**: `https://docs.railway.com/api/llms-docs.md`
+- **LLM summary**: `https://railway.com/llms.txt`
+- **Templates**: `https://railway.com/llms-templates.md`
+- **Changelog**: `https://railway.com/llms-changelog.md`
+- **Blog**: `https://blog.railway.com/llms-blog.md`
+- **Direct doc pages**: `https://docs.railway.com/<path>` (for example, `cli/up`, `networking/domains`, `observability/logs`)
+
+Tip: append `.md` to any `docs.railway.com` page URL to get a markdown version suitable for LLM consumption.
+
+Common doc paths:
+
+| Topic | Path |
+|---|---|
+| Agent setup | `agents`, `ai/agent-skills`, `ai/mcp-server` |
+| CLI reference | `cli`, `cli/<command>` |
+| Projects | `projects` |
+| Deployments | `deployments` |
+| Volumes | `volumes` |
+| Variables | `variables` |
+| Infrastructure as Code | `infrastructure-as-code`, `infrastructure-as-code/reference` |
+| Public networking | `networking/public-networking` |
+| Private networking | `networking/private-networking` |
+| Domains, CDN, WAF | `networking/domains`, `networking/cdn`, `networking/waf` |
+| Outbound networking | `networking/outbound-networking`, `networking/static-outbound-ips` |
+
+Fetch official docs first for product behavior questions. Use Central Station only when you need community evidence, prior incidents, or implementation anecdotes.
+
+
+## Central Station (community)
+
+Search and browse Railway's community platform for prior discussions, issue patterns, and field solutions.
+
+### Recent threads
+
+```bash
+curl -s 'https://station-server.railway.com/gql' \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ threads(first: 10, sort: recent_activity) { edges { node { slug subject status upvoteCount createdAt topic { slug displayName } } } } }"}'
+```
+
+Filter by topic with the `topic` parameter (`"questions"`, `"feedback"`, `"community"`, `"billing"`):
+
+```bash
+curl -s 'https://station-server.railway.com/gql' \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ threads(first: 10, sort: recent_activity, topic: \"questions\") { edges { node { slug subject status topic { displayName } upvoteCount } } } }"}'
+```
+
+Sort options: `recent_activity` (default), `newest`, `highest_votes`.
+
+### Search threads
+
+```bash
+curl -s 'https://station-server.railway.com/gql' \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ threads(first: 10, search: \"<search-term>\") { edges { node { slug subject status } } } }"}'
+```
+
+### LLM data export
+
+Bulk search alternative, fetches all public threads with full content:
+
+```bash
+curl -s 'https://station-server.railway.com/api/llms-station'
+```
+
+### Read a full thread
+
+```bash
+curl -s 'https://station-server.railway.com/api/threads/<slug>?format=md'
+```
+
+Thread URLs follow the format: `https://station.railway.com/{topic_slug}/{thread_slug}`
+
+Community threads are anecdotal. Always pair with official docs when the answer informs an operational decision.
+
+
+## GraphQL helper
+
+All GraphQL operations use the API helper script, which handles authentication automatically:
+
+```bash
+scripts/railway-api.sh '<query>' '<variables-json>'
+```
+
+The script reads the API token from `~/.railway/config.json` and sends requests to `https://backboard.railway.com/graphql/v2`.
+
+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:
+
+```bash
+scripts/railway-api.sh \
+  '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}}'
+```
+
+Common `ProjectUpdateInput` fields: `name`, `isPublic`, `prDeploys`, `botPrEnvironments`.
+
+
+## Service mutations
+
+The CLI can create services (`railway add`) but cannot rename them or change icons. Use GraphQL:
+
+```bash
+scripts/railway-api.sh \
+  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
+    serviceUpdate(id: $id, input: $input) { id name icon }
+  }' \
+  '{"id":"<service-id>","input":{"name":"new-name"}}'
+```
+
+`ServiceUpdateInput` fields: `name`, `icon` (image URL, animated GIF, or devicons URL like `https://devicons.railway.app/postgres`).
+
+Get the service ID from `railway service list --json`.
+
+
+## Service creation via GraphQL
+
+Prefer `railway add` for most cases. Use GraphQL for programmatic or advanced use:
+
+```bash
+scripts/railway-api.sh \
+  'mutation createService($input: ServiceCreateInput!) {
+    serviceCreate(input: $input) { id name }
+  }' \
+  '{"input":{"projectId":"<project-id>","name":"my-service","source":{"image":"nginx:latest"}}}'
+```
+
+`ServiceCreateInput` fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `projectId` | String! | Target project (required) |
+| `name` | String | Service name (auto-generated if omitted) |
+| `source.image` | String | Docker image (for example, `nginx:latest`) |
+| `source.repo` | String | GitHub repo (for example, `user/repo`) |
+| `branch` | String | Git branch for repo source |
+| `environmentId` | String | Create only in a specific environment |
+
+After creating a service via GraphQL, configure it with a JSON config patch including `isCreated: true` (see [configure.md](configure.md)).
+
+
+## Metrics queries
+
+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 \
+  '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"]}'
+```
+
+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`.
+
+Optional parameters: `endDate` (defaults to now), `sampleRateSeconds`, `averagingWindowSeconds`. Use `groupBy: ["SERVICE_ID"]` without `serviceId` to query all services in an environment at once. Valid `MetricTag` values for `groupBy`: `SERVICE_ID`, `DEPLOYMENT_ID`, `DEPLOYMENT_INSTANCE_ID`, `REGION`.
+
+Get the environment ID from `railway status --json`. Get service IDs from `railway service list --json`.
+
+## Template search
+
+Use the CLI for template search:
+
+```bash
+railway templates search redis --verified true --json
+railway templates search --category Storage --limit 10 --json
+railway templates search --after <cursor> --json
+railway templates list --json
+railway templates create --project <project> --environment production --json
+```
+
+The CLI search command doesn't require authentication and supports pagination with `pageInfo.endCursor`. Prefer CLI template commands for search, listing owned templates, creating drafts, publishing, unpublishing, and deleting. Use GraphQL only for template workflows the CLI cannot express.
+
+Use GraphQL only when the CLI output isn't enough for the workflow:
+
+```bash
+scripts/railway-api.sh \
+  '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}'
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | String | Search term |
+| `verified` | Boolean | Only verified templates |
+| `recommended` | Boolean | Only recommended templates |
+| `first` | Int | Number of results |
+
+Common template codes: `ghost`, `strapi`, `minio`, `n8n`, `uptime-kuma`, `umami`, `postgres`, `redis`, `mysql`, `mongodb`.
+
+Deploy a found template via CLI:
+
+```bash
+railway deploy --template <template-code>
+```
+
+Manage owned templates via CLI:
+
+```bash
+railway templates publish <template-id> --category Other --description "Deploy and Host My App with Railway" --readme-file README.md --json
+railway templates update <template-id> --category Other --description "Updated description" --readme-file README.md --json
+railway templates unpublish <template-id-or-code> --yes --json
+railway templates delete <template-id-or-code> --yes --json
+```
+
+### GraphQL template deployment
+
+For deploying into a specific environment or tracking the workflow, use the two-step GraphQL flow:
+
+**Step 1**: Fetch the template config:
+
+```bash
+scripts/railway-api.sh \
+  'query template($code: String!) {
+    template(code: $code) { id serializedConfig }
+  }' \
+  '{"code":"postgres"}'
+```
+
+**Step 2**: Deploy with `templateDeployV2`:
+
+```bash
+scripts/railway-api.sh \
+  'mutation deploy($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) { projectId workflowId }
+  }' \
+  '{"input":{
+    "templateId":"<id-from-step-1>",
+    "serializedConfig":<config-object-from-step-1>,
+    "projectId":"<project-id>",
+    "environmentId":"<env-id>",
+    "workspaceId":"<workspace-id>"
+  }}'
+```
+
+`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 } }' '{}'`.
+
+
+## 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)