Railway CLI

Sommario esecutivo

La CLI di Railway, verificata live al 2 maggio 2026, risulta attualmente su v4.44.0 sia nel repository sorgente sia nella pagina releases. La documentazione ufficiale CLI è molto più ricca rispetto alla classica landing page: oltre ai comandi noti (login, link, up, logs, variables, environment, service, ssh), nel reference navigabile compaiono anche deployment, bucket, agent, docs, upgrade, starship e altri. Le installazioni ufficialmente documentate passano da Homebrew, npm, Scoop, script shell, binari precompilati e build da sorgente; il package npm richiede Node.js >= 16.0.0, mentre la build Rust richiede rustc 1.85.0.

Operativamente, la CLI è fortissima su deploy locale, scripting, CI/CD, linking directory→project/service, streaming log, SSH nativo, iniezione variabili in processi locali, e su alcune automazioni di storage e funzioni. La Web UI resta superiore per rollback storico esplicito, dashboard di osservabilità cross-service, shared variables, approvazioni deploy GitHub, staged changes complete e alcune azioni amministrative più visive. In particolare, il rollback documentato di un deploy precedente è esplicitamente disponibile in dashboard, mentre la CLI documenta redeploy, restart e down, ma non un comando di rollback arbitrario a una release storica.

La documentazione e i changelog mostrano anche drift documentale da tenere presente in produzione. Esempi concreti: i release notes introducono railway service delete in v4.42.0, railway service list in v4.41.0 con deprecazione di status --all, e railway skills in v4.39.0, ma le pagine comando non sono sempre già perfettamente allineate a questi cambiamenti. Inoltre, guide più vecchie o snippet esterni possono usare forme legacy come railway environment create, mentre il reference corrente usa railway environment new; railway link --team è marcato deprecato a favore di --workspace.

Sul piano sicurezza, Railway distingue bene account token, workspace token, project token e OAuth, ciascuno con scope e casi d’uso diversi. Per CI/CD di singolo progetto l’opzione più stretta è RAILWAY_TOKEN con project token; per operazioni di livello account/workspace si usa RAILWAY_API_TOKEN. La CLI rispetta anche opt-out della telemetria tramite DO_NOT_TRACK=1 o RAILWAY_NO_TELEMETRY=1. Attenzione però a un issue aperto, ufficiale, su token workspace-scoped non sempre accettati dal CLI in alcune versioni recenti; è quindi prudente validare subito la combinazione versione CLI + tipo token + comando prima di standardizzare una pipeline.

Indice

• Stato corrente, compatibilità e prerequisiti
• Installazione, autenticazione e linking
• Progetti, ambienti, servizi, variabili, database e storage
• Deployment, release, rollback, GitHub e CI/CD
• Osservabilità, sicurezza, troubleshooting e migrazione
• Riferimento completo dei comandi e workflow

Stato corrente, compatibilità e prerequisiti

Al momento della verifica live, il repository GitHub ufficiale della CLI pubblica v4.44.0 come release più recente, datata 28 aprile 2026. Il Cargo.toml del repository riporta anch’esso version = "4.44.0" ed edition = "2024", con rust-version = "1.85.0". Il package npm ufficiale dichiara engines.node: >=16.0.0. Questo consente di distinguere chiaramente tre livelli di compatibilità: compatibilità runtime del wrapper npm, compatibilità dei binari precompilati, e prerequisiti per build da sorgente.

Area	Stato / requisito	Evidenza
Versione CLI verificata live	v4.44.0
npm package engine	Node >= 16.0.0
Build da sorgente Rust	rustc 1.85.0, edition 2024
Install methods ufficiali	Homebrew, npm, Scoop, shell script, binari pre-built, source
Upgrade auto-rilevato	Homebrew, npm, Bun, Cargo, Scoop, Shell

Dal lato sistema operativo, la documentazione utente dichiara installazione via Homebrew su macOS, npm su macOS/Linux/Windows, shell script su macOS/Linux/Windows via WSL, Scoop su Windows, oltre a binari precompilati e source build. Il repository README aggiunge anche Cargo, Bash installer e AUR; lo script install.sh dichiara supporto implementativo per darwin, linux, linux_musl (Alpine), win (Git Bash) e freebsd, e il set di target compilati include più architetture Apple, Windows e Linux. Le release mostrano asset firmati/checksummati per Apple Silicon, Windows ARM/x86, Linux musl e pacchetto .deb; il README ufficiale elenca anche i comandi di installazione per Homebrew, npm, Cargo, Bash e Scoop.

OS / piattaforma	Metodo consigliato	Note tecniche
macOS Intel / Apple Silicon	brew install railway oppure binario prebuilt	Homebrew è il percorso più lineare; sono presenti asset aarch64-apple-darwin nelle release.
Linux glibc / distro Debian-like	npm, shell installer, .deb, Cargo	Le release mostrano anche amd64.deb; lo script supporta Linux e Linux musl.
Alpine / musl	binario musl o shell installer	Lo script cita esplicitamente linux_musl (Alpine).
Windows	Scoop, npm, zip/tarball; shell script via WSL lato docs	La doc utente raccomanda WSL per lo shell script; l’installer interno sa anche rilevare Git Bash.
FreeBSD	supporto nello script installativo	Supporto presente nello script, ma non enfatizzato nella pagina utente principale.

I prerequisiti operativi più rilevanti cambiano per comando. railway connect richiede il client database corretto installato localmente (psql, mysql, redis-cli, mongosh) e, per accesso esterno al DB, un TCP Proxy attivo. railway ssh usa il client ssh di sistema e richiede una chiave SSH registrata. railway dev è experimental e richiede Docker con Docker Compose; mkcert è opzionale per HTTPS locale.

Installazione, autenticazione e linking

Per l’installazione, la linea guida pratica è semplice: usare Homebrew su macOS, Scoop o npm su Windows, npm o binario su Linux, e Cargo solo se si vuole controllare il processo di build. Il package manager npm ufficiale è @railway/cli, non un binario npm generico con nome diverso; il repository README ufficiale documenta npm install -g @railway/cli, mentre la pagina railway upgrade riconosce anche Bun per l’aggiornamento automatico.

# macOS
brew install railway

# npm
npm install -g @railway/cli

# Rust / Cargo
cargo install railwayapp --locked

# Bash installer
bash <(curl -fsSL cli.new)

# Windows / Scoop
scoop install railway

Questi metodi sono tutti direttamente documentati dal README ufficiale e/o dalla pagina di installazione/upgrade.

Per binari manuali, il flusso consigliabile è: scaricare l’asset corretto dalla release più recente, verificare lo SHA256 pubblicato nella release, estrarre il binario e posizionarlo in PATH. Railway pubblica asset per piattaforme multiple e allega checksum per ogni file. Se l’auto-detection di railway upgrade fallisce, la pagina ufficiale raccomanda di eseguire il comando di upgrade manuale coerente con il metodo d’installazione.

L’autenticazione ha due percorsi principali. Il flusso interattivo è railway login, che apre il browser per OAuth locale; con --browserless usa pairing code e URL manuale. In ambienti headless o CI, Railway raccomanda i token via environment variables: RAILWAY_TOKEN per contesto progetto/ambiente e RAILWAY_API_TOKEN per operazioni account/workspace. La CLI userà automaticamente questi token se sono presenti e non chiederà login interattivo.

Tipo token	Variabile ambiente	Scope	Uso corretto
Project token	RAILWAY_TOKEN	singolo environment di un progetto	deploy/app automation di servizio o progetto
Account token	RAILWAY_API_TOKEN	tutte le risorse dell’account	script personali, local development
Workspace token	RAILWAY_API_TOKEN	una workspace specifica	team CI/CD e automazione condivisa
OAuth token	n/d per CLI standard	permessi utente-granted	app terze che agiscono per conto utente

Il CLI/working-directory binding è un concetto centrale. railway link collega directory corrente a workspace/project/environment/service e salva il binding in una cartella .railway alla root del progetto, normalmente ignorata da Git. È questo stato locale che fa funzionare railway up, railway logs, railway run, railway shell, railway ssh senza dover ripetere ogni volta gli ID. railway unlink rimuove il binding intero oppure, con --service, solo l’associazione al servizio.

Caso	CLI	Comportamento
Creare nuovo progetto e linkarlo	railway init	crea il progetto e collega subito la directory corrente
Collegare directory a progetto esistente	railway link	selezione interattiva o flags --workspace/--project/--environment/--service
Rimuovere service binding ma mantenere project/env	railway unlink --service	utile in monorepo o quando si cambia target service
Verificare contesto corrente	railway status	stampa progetto/environment/service collegati; con --json ritorna metadati strutturati

Progetti, ambienti, servizi, variabili, database e storage

Il modello dati esposto dalla CLI segue da vicino quello della piattaforma: workspace → project → environment → service, con variabili sia per-service sia condivisibili a livello environment/project tramite Web UI o Public API. railway environment gestisce creazione, duplicazione, cancellazione, editing config e link dell’ambiente; railway variable gestisce le variabili del servizio; railway add crea servizi vuoti, DB, servizi da repo GitHub o immagini Docker. Per i database, railway deploy è riservato ai template pre-costruiti, mentre railway up è il deploy del proprio codice locale.

flowchart TB
    W[Workspace] --> P[Project]
    P --> E1[Environment production]
    P --> E2[Environment preview]
    E1 --> S1[Service API]
    E1 --> S2[Service Postgres]
    E2 --> S3[Service API preview]
    SV[Shared variables] --> E1
    SV --> E2
    S2 -->|reference variable| S1

Questo flusso riflette la separazione tra environment, servizi e variabili condivise/reference variables documentata da Railway.

Le shared variables non sono un concetto di prima classe nella CLI corrente: la pagina railway variable parla di variabili per-service, mentre la documentazione piattaforma spiega che le shared variables si definiscono dal dashboard e, via API, si ottengono/aggiornano omettendo serviceId. Se devi industrializzare differenze tra ambienti o clonare intere collezioni di variabili, l’API GraphQL di Railway è più completa del CLI. Questo è uno dei punti in cui la Web UI e la API superano chiaramente il reference CLI.

Per database e migrazioni, Railway fornisce template ufficiali (PostgreSQL, MySQL, Redis, MongoDB), supporta qualsiasi database deployabile come immagine Docker o template marketplace, e raccomanda l’uso di pre-deploy commands per migrazioni ORM/SQL. Il pre-deploy command gira fra build e deploy, nel private network, con le environment variables disponibili; se fallisce, il deploy non procede. Questo è il meccanismo corretto per prisma migrate deploy, drizzle-kit migrate, seeding o warmup che devono avvenire ad ogni rilascio.

Tema	CLI / piattaforma	Nota architetturale
Aggiungere PostgreSQL/MySQL/Redis/Mongo	railway add --database <type> oppure railway deploy -t <template>	deploy è per template; up è per codice locale.
Connettersi a DB da terminale	railway connect	richiede client DB locale e TCP Proxy attivo
Variabili di servizio	railway variable list/set/delete	--skip-deploys evita redeploy al set
Shared variables	UI/API	non esposte come workflow completo nel comando variable
Storage bucket	railway bucket ...	crea, rinomina, cancella bucket e credenziali S3-compatibili
Volume persistente	railway volume ...	pagina presente nel reference; dettagli operativi non completamente estratti in questa verifica

Sui “plugins”, la documentazione ufficiale corrente non mostra una plugin API generica della CLI paragonabile, per esempio, ai plugin di kubectl o Terraform. L’estensibilità ufficiale oggi ruota piuttosto attorno a Railway Agent, Agent Skills, Claude Code plugin e MCP server, che sono strumenti AI/workflow dell’ecosistema Railway, non plugin classici caricati dal binario CLI. In altre parole: per workflow estesi si punta su API GraphQL, skill AI e integrazioni, non su una plugin-architecture CLI tradizionale.

Deployment, release, rollback, GitHub e CI/CD

Il deploy locale standard è railway up: la CLI comprime, carica il contenuto della directory corrente, Railway costruisce l’immagine con Railpack o con il Dockerfile se presente, poi effettua il deploy. In modalità normale i log vengono streammati in tempo reale; con --ci vengono mostrati solo build logs e il processo esce al termine della build; con --json l’output dei log passa in JSON e si attiva implicitamente la modalità CI. railway deploy, al contrario, serve a deployare template pre-built, in particolare DB e altre soluzioni di marketplace/template.

flowchart LR
    A[Repo locale] --> B[railway link]
    B --> C[railway up --ci]
    C --> D[Upload archivio]
    D --> E[Build Railpack o Dockerfile]
    E --> F[Pre-deploy command]
    F --> G[Deploy]
    G --> H[Healthcheck]
    H --> I[Logs / Metrics / deployment_status GitHub]

Questo è il pipeline model documentato da Railway per CLI deploy, pre-deploy, deployment lifecycle e GitHub post-deploy hooks.

Per integrazione con GitHub, esistono due strade distinte. La prima è sorgente GitHub come service source, configurabile da dashboard (Connect Repo) o da CLI con railway add --repo <owner/repo>. La seconda è deploy locale via CLI su un servizio vuoto o già creato, utile quando non vuoi che il source-of-truth del deploy sia GitHub ma il workspace locale. Se un servizio è connesso a repo GitHub, Railway può autodeployare ogni nuovo commit sul branch collegato; per far funzionare autodeploy è necessario che almeno un membro del progetto abbia account GitHub connesso e accesso contributor al repository.

Il confronto CLI vs UI, sul flusso release, è netto:

Azione	CLI	Web UI	Differenza tecnica
Deploy codice locale	railway up	non come feature primaria	vantaggio CLI assoluto per loop locale
Connettere repo GitHub a servizio	railway add --repo	Connect Repo	UI più ricca per branch/autodeploy/approvals
Trigger latest commit GitHub	non documentato come comando dedicato; v4.44.0 introduce redeploy --from-source nei release notes	Deploy Latest Commit da command palette	docs e release non ancora perfettamente allineati
Rollback a deployment storico	non documentato come comando dedicato	supportato via menu Deployments	UI superiore per rollback vero
Restart / redeploy ultimo deploy	railway restart, railway redeploy	sì	parità funzionale sui casi basici
Rimuovere ultimo deploy riuscito	railway down	“Remove” su deployment completato	semantica non identica al rollback
Log stream	railway logs	deployment panel / log explorer	UI migliore su cross-service e date range; CLI ottimo per stream/script

Per CI/CD, la combinazione più pulita è: installa CLI, esporta RAILWAY_TOKEN per progetto/ambiente target, poi usa railway up --ci oppure railway link --project ... --environment ... --service ... --json seguito da railway up --ci. Se servono operazioni di livello account/workspace (list, selezione dinamica progetti, ecc.), bisogna passare a RAILWAY_API_TOKEN e quindi a un token più ampio. Railway espone anche deployment_status su GitHub, così da concatenare smoke test o job post-deploy.

name: deploy-railway

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Railway CLI
        run: npm install -g @railway/cli

      - name: Deploy
        run: railway up --ci --service api
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

Questo workflow segue il modello ufficiale “token in env, niente login interattivo, deploy CI-oriented con --ci”.

name: post-deploy-smoke

on:
  deployment_status:

jobs:
  smoke:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Smoke test
        run: curl -fsS "$TARGET_URL/health"
        env:
          TARGET_URL: ${{ vars.TARGET_URL }}

Railway documenta espressamente l’uso dell’evento deployment_status per azioni GitHub post-deploy.

#!/usr/bin/env bash
set -euo pipefail

: "${RAILWAY_TOKEN:?RAILWAY_TOKEN non impostato}"

export DO_NOT_TRACK=1

railway link \
  --project "${RAILWAY_PROJECT_ID}" \
  --environment "${RAILWAY_ENVIRONMENT}" \
  --service "${RAILWAY_SERVICE}" \
  --json

railway up --ci --verbose

Questo script è coerente con linking non interattivo, token-based auth e opt-out telemetria documentati da Railway.

$ErrorActionPreference = 'Stop'

if (-not $env:RAILWAY_TOKEN) {
    throw "RAILWAY_TOKEN mancante"
}

$env:DO_NOT_TRACK = "1"

railway link `
  --project $env:RAILWAY_PROJECT_ID `
  --environment $env:RAILWAY_ENVIRONMENT `
  --service $env:RAILWAY_SERVICE `
  --json

railway up --ci

Anche su PowerShell il pattern resta uguale: token env, linking non interattivo, deploy CI mode.

Osservabilità, sicurezza, troubleshooting e migrazione

Railway offre osservabilità nativa su tre piani: CLI logs, UI log explorer / deployment panel, e osservability dashboard con widget, metriche, filtri e monitor. Il comando railway logs è centrato su deploy/build/runtime logs e supporta stream live, fetch storico (--lines, --since, --until), filtering query-based e output JSON. La UI resta superiore quando serve correlazione multi-servizio, date-range browsing, visualizzazione colonne, widget personalizzati e monitor con notifiche.

Le metriche native sono container-level: CPU, memoria, disco e rete. Railway dichiara fino a 30 giorni di dati metrici per progetto nella pagina metrics; un’altra pagina di use cases menziona fino a 90 giorni di log retention su workspace Pro. Per application-level telemetry, tracing o retention più lunga, la doc raccomanda integrazione terza parte via SDK vendor oppure OpenTelemetry/OTLP. Railway non offre un log drain stdout→endpoint esterno come feature nativa; se serve forwarding raw stdout, va eseguito un forwarder dedicato come servizio separato.

Sul piano sicurezza, i punti davvero importanti sono cinque. Primo: scegliere il token più stretto possibile, con preferenza per project token nelle pipeline di deploy a progetto singolo e workspace token solo quando servono operazioni cross-project all’interno della stessa workspace. Secondo: ricordare che dashboard e CLI sono soggetti a enforcement 2FA a livello workspace, mentre i token continuano a funzionare per automazione anche con 2FA enforcement attivo. Terzo: gli OAuth app scopes sono granulari (workspace:viewer/member/admin, project:viewer/member, offline_access, ecc.) e i grants possono essere revocati in qualsiasi momento dagli Authorized Apps settings. Quarto: la CLI raccoglie telemetria minima su comandi/OS/architettura/versione/successo, ma non codice sorgente né valori delle env var; l’opt-out è immediato con DO_NOT_TRACK=1 o RAILWAY_NO_TELEMETRY=1. Quinto: in debug con log verbosi, evitare dump non redatti del token.

I problemi ricorrenti in produzione non sono tanto di sintassi quanto di scope, contesto linkato, dipendenze locali e drift versione/documentazione:

Problema	Causa probabile	Correzione operativa
Unauthorized / Invalid or expired Railway token	token errato per il comando, conflitto fra RAILWAY_TOKEN e RAILWAY_API_TOKEN, o issue aperto su workspace-scoped token	verificare scope token, unset di variabili concorrenti, usare account token per comandi account-level, project token per deploy, testare whoami/list subito dopo install
railway connect non apre il client DB	mancano psql/mysql/redis-cli/mongosh o non c’è TCP Proxy	installare il client corretto e attivare TCP Proxy
railway ssh fallisce	mancano chiave SSH registrata o token non adatto alla gestione chiavi	eseguire login utente o workspace token adeguato; registrare chiave locale
Deploy non include file attesi	.gitignore ha escluso path importanti	usare railway up --no-gitignore o ridefinire root/path
Variabili aggiornate ma deploy non coerente	variable set --skip-deploys evita il trigger oppure il deploy non è stato rifatto	usare railway redeploy/restart a seconda del caso
Script legacy con railway environment create	cambio nomenclatura nei reference correnti	migrare a railway environment new

Dal punto di vista migrazione/versioning, i change log recenti mostrano uno sviluppo molto rapido della CLI. Le release più rilevanti da conoscere oggi sono:

Versione	Cambiamento principale	Impatto pratico
v4.44.0	redeploy --from-source per latest commit/image	avvicina la CLI a un “deploy latest source” senza upload locale
v4.43.0	SSH nativo di default, rimosso relay WebSocket	migliore allineamento con ssh di sistema e con key handling classico
v4.42.1	fix installer + link non interattivo/agent mode	utile per automazione e ambienti headless
v4.42.0	aggiunto service delete	attenzione: release e docs non risultano perfettamente allineati
v4.41.0	aggiunto service list, deprecato status --all	aggiornare script e aspettative sui comandi servizi
v4.39.0	aggiunto skills	comando emerso dai release notes, non ancora centrale nel CLI reference classico

Questioni aperte / limiti. Non emerge, nelle fonti ufficiali correnti consultate, una migration guide consolidata “v2/v3 → v4”. La migrazione va quindi gestita pragmaticamente tramite release notes, alias/deprecations del reference e test delle pipeline. Inoltre, alcune pagine comando (project, volume) non sono state estraibili in modo completo nel campionamento live qui sintetizzato; per questi casi conviene sempre affiancare la documentazione con railway <comando> --help in ambiente reale.

Riferimento completo dei comandi e workflow

Prima della matrice comandi, conviene fissare due convenzioni. La prima: i global options più ricorrenti sono --service/-s, --environment/-e, --json, --yes/-y, --help/-h, --version. La seconda: la documentazione web non pubblica una matrice formale e centralizzata dei codici di uscita per tutti i comandi; in pratica, nei workflow automatizzati va trattato come stabile solo il pattern successo = 0, errore = non-zero, salvo validazione esplicita in test di pipeline.

Comando	Sintassi essenziale	Flag principali	Esempio	Output atteso	Exit code / note	Fonte
login	railway login [--browserless]	--browserless	railway login --browserless	browser OAuth o pairing code + URL	non documentato formalmente; usa token env se presenti
logout	railway logout	—	railway logout	conferma implicita, credenziali rimosse	invalida il token locale CLI
whoami	railway whoami [--json]	--json	railway whoami --json	identità utente corrente	utile per smoke test auth
init	railway init [OPTIONS]	--name, --workspace, --json	railway init --name my-app	crea progetto e lo linka	alias railway new
link	railway link [OPTIONS]	--project, --environment, --service, --workspace, --json	railway link -p proj -e production -s api	binding .railway creato/aggiornato	--team deprecato
unlink	railway unlink [OPTIONS]	--service, --yes, --json	railway unlink --service	rimozione binding service o project	utile in monorepo
list	railway list [--json]	--json	railway list --json	elenco progetti su tutte le workspace	il progetto linkato è evidenziato in output testuale
status	railway status [--json]	--json	railway status --json	contesto attuale e metadati progetto	riferimento primario per capire “dove” punta la directory
open	`railway open [-p	--print]`	--print	railway open --print	URL dashboard o apertura browser	utile in script con --print
docs	railway docs	—	railway docs	apre docs nel browser	nessun output strutturato documentato
upgrade	railway upgrade [--check]	--check	railway upgrade --check	rileva install method o esegue upgrade	riconosce Homebrew, npm, Bun, Cargo, Scoop, Shell
up	railway up [PATH] [OPTIONS]	--ci, --detach, --service, --environment, --project, --no-gitignore, --path-as-root, --verbose, --json	railway up --ci --service api	upload + build + deploy, con stream logs o JSON	--json implica CI mode
deploy	railway deploy [OPTIONS]	--template, --variable	railway deploy -t postgres	deploy di template prebuilt	non usare per codice locale
redeploy	railway redeploy [OPTIONS]	--service, --yes, --json	railway redeploy -s api	nuovo deploy dalla stessa source	release v4.44.0 aggiunge --from-source, docs pagina non ancora allineata
restart	railway restart [OPTIONS]	--service, --yes, --json	railway restart -s api	restart dell’ultimo deploy senza rebuild	riusa immagine esistente
down	railway down [OPTIONS]	--service, --environment, --yes	railway down -s api -y	rimuove l’ultimo deploy riuscito	non cancella il servizio
add	railway add [OPTIONS]	--database, --service, --repo, --image, --variables, --json, --verbose	railway add --repo org/repo	crea servizio vuoto/DB/repo/image	collega automaticamente il nuovo servizio alla directory
delete	railway delete [OPTIONS]	--project, --yes, --2fa-code, --json	railway delete -p myproj -y	elimina in modo permanente il progetto	comando distruttivo
logs	railway logs [OPTIONS]	--service, --environment, --deployment, --build, --lines, --filter, --latest, --since, --until, --json	railway logs -s api -f '@level:error'	stream live o fetch storico	--lines/--since/--until disabilitano streaming
shell	railway shell [OPTIONS]	--service, --silent	railway shell -s api	nuova shell locale con env vars Railway iniettate	setta IN_RAILWAY_SHELL=true
ssh	railway ssh [OPTIONS]	--project, --service, --environment, --deployment-instance, --session, --identity-file	railway ssh --service api --session deploy	shell nel container remoto	usa ssh di sistema; tmux persistente supportato
connect	railway connect [SERVICE] [OPTIONS]	--environment	railway connect postgres	lancia psql/mysql/redis-cli/mongosh	richiede client locale e TCP Proxy
domain	railway domain [DOMAIN] [OPTIONS]	--port, --service, --json	railway domain example.com -s api	dominio Railway o istruzioni DNS	custom domain richiede CNAME + TXT
scale	railway scale [OPTIONS] --<REGION>=<N>	--service, --environment, --json, region flags dinamici	railway scale --europe-west4=2	applica replica count per regione	update region config causa redeploy automatico
completion	railway completion <shell>	shell = bash/zsh/fish/powershell/elvish	railway completion zsh	script di completion	da inserire nel profilo shell
starship	railway starship	—	railway starship	JSON metadata per prompt integration	focalizzato su integrazione Starship
agent	railway agent [OPTIONS]	--prompt, --json, --thread-id, --service, --environment	railway agent -p "show failed deploys"	risposta NL o JSON	richiede login utente; RAILWAY_TOKEN non supportato
bucket	railway bucket <subcommand> ...	--environment, --bucket, --json, --yes, --2fa-code	railway bucket credentials --bucket assets --json	tabella bucket / dettagli / credenziali S3-like	create/delete possono passare in staged changes se presenti
dev	`railway dev <up	down	clean	configure>`	--service, --remove (configure)	railway dev up
deployment	`railway deployment <list	up	redeploy>`	--service, --environment, --limit, --json	railway deployment list --limit 50 --json	elenco deployment con ID/stato/timestamp
project	railway project ...	non estratto completamente	railway project --help	gestione progetto	pagina presente nel CLI reference; dettagliare live con --help
volume	railway volume ...	non estratto completamente	railway volume --help	gestione volumi persistenti	pagina presente nel CLI reference; dettagliare live con --help

Per i comandi “gruppo”, i subcomandi importanti sono questi:

Gruppo	Subcomando	Sintassi essenziale	Esempio	Note	Fonte
variable	list	railway variable list [-s SERVICE] [-e ENV] [-k] [--json]	railway vars list -k	-k stampa KEY=VALUE
variable	set	railway variable set KEY=VALUE ...	railway vars set API_URL=https://x	--stdin, --skip-deploys supportati
variable	delete	railway variable delete KEY ...	railway vars delete API_URL	rimuove variabile servizio
environment	link	railway environment link [ENV]	railway env link production	collega environment al project locale
environment	new	railway environment new NAME [--duplicate ENV] [--json]	railway env new preview --duplicate production	alias legacy --copy; preferire new, non create
environment	delete	railway environment delete ENV [-y] [--2fa-code]	railway env delete preview -y	distruttivo
environment	edit	railway environment edit ...	railway env edit -e production --service-config api deploy.startCommand "node server.js"	supporta dot-path notation e staged changes
environment	config	railway environment config [-e ENV] [--json]	railway env config --json	dump config environment
functions	list	railway functions list [-e ENV]	railway fn list	elenca funzioni serverless
functions	new	railway functions new -p PATH -n NAME [--cron] [--http] [--serverless]	railway fn new -p ./functions/ping.ts -n ping --http	crea HTTP o cron function
functions	push	railway functions push -p PATH [-w]	railway fn push -p ./functions/ping.ts -w	--watch supportato
functions	pull	railway functions pull	railway fn pull	allinea locale con remoto
functions	delete	railway functions delete -f FUNCTION [-y]	railway fn delete -f ping -y	cancella funzione
functions	link	railway functions link	railway fn link	linking manuale
service	link	railway service link [SERVICE]	railway service link api	collega servizio al contesto corrente
service	status	railway service status [-a] [--json]	railway service status -a	-a/--all per tutti i servizi environment
service	logs	railway service logs ...	railway service logs -n 200	wrapper tematico di logs
service	redeploy	railway service redeploy [-y] [--json]	railway service redeploy -y	wrapper di redeploy
service	restart	railway service restart [-y] [--json]	railway service restart -y	wrapper di restart
service	scale	railway service scale --<REGION>=<N>	railway service scale --us-west1=2	allineato a scale
deployment	list	railway deployment list [--limit N] [--json]	railway deployment list --limit 100	stati: SUCCESS, FAILED, CRASHED, BUILDING, ecc.
deployment	up	railway deployment up ...	railway deployment up	alias/logical wrapper di up
deployment	redeploy	railway deployment redeploy ...	railway deployment redeploy	alias/logical wrapper di redeploy
bucket	list	railway bucket list [--json]	railway bucket list --json	bucket dell’environment corrente
bucket	create	railway bucket create [NAME] [-r REGION] [--json]	railway bucket create assets -r ams	crea bucket; può essere staged
bucket	delete	railway bucket delete -b BUCKET [-y] [--2fa-code] [--json]	railway bucket delete -b assets -y	comando distruttivo
bucket	info	railway bucket info -b BUCKET [--json]	railway bucket info -b assets	size, object count, region
bucket	credentials	railway bucket credentials -b BUCKET [--reset]	railway bucket credentials -b assets --json	mostra o ruota credenziali S3-compatibili
bucket	rename	railway bucket rename -b BUCKET -n NEWNAME [--json]	railway bucket rename -b assets -n assets-prod	rename interattivo o flag
dev	up	railway dev up	railway dev up	avvia image-based services locali
dev	down	railway dev down	railway dev down	stop stack locale
dev	clean	railway dev clean	railway dev clean	stop + remove volumes/data
dev	configure	railway dev configure [--service NAME] [--remove [SERVICE]]	railway dev configure --service api	configura come eseguire code services locali

Infine, i gap da conoscere perché incidono su workflow e manutenzione:

Gap / drift	Stato osservato	Impatto
service delete presente nei release notes v4.42.0 ma non ben evidenziato nella pagina service consultata	doc drift	verificare railway service delete --help nella versione installata prima di automatizzare
service list introdotto in v4.41.0 con deprecazione status --all, ma la pagina service mostra ancora fortemente status -a	doc drift	aggiornare script con test di versione
skills introdotto in v4.39.0 ma non parte stabile del reference CLI classico consultato	feature emergente	utile in ecosistema Agent Skills, meno in CI classico
project e volume esistono nel nav reference, ma qui non sono stati estratti integralmente	incompletezza documentale del campionamento	usare railway project --help e railway volume --help come complemento operativo

Fonti primarie di riferimento consigliate. Per uso pratico quotidiano, le fonti più autorevoli e da tenere bookmarkate sono: il CLI reference di Railway, il repository GitHub ufficiale, la pagina GitHub Releases, la sezione Public API per gaps CLI/UI, e le pagine piattaforma su Variables, Services, Deployments, Logs, Metrics, GitHub autodeploys e Pre-deploy commands. Tutte le affermazioni di questo report sono state ricondotte a queste fonti primarie ufficiali in lingua inglese.