diff --git a/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs b/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs index 4a59dca5fd3..ffe26b931dd 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs @@ -3,6 +3,7 @@ #endif using ChilliCream.Nitro.CommandLine.Helpers; +using ChilliCream.Nitro.CommandLine.Services.Sessions; namespace ChilliCream.Nitro.CommandLine.Commands.Launch; @@ -27,10 +28,36 @@ private static Task ExecuteAsync( CancellationToken cancellationToken) { var console = services.GetRequiredService(); + var sessionService = services.GetRequiredService(); + var browser = services.GetRequiredService(); - SystemBrowser.Open(Constants.NitroWebUrl); - console.OkLine($"[link={Constants.NitroWebUrl}]Nitro[/] is launched!"); + var url = ResolveUrl(sessionService.Session); + + browser.Open(url); + console.OkLine($"[link={url.EscapeMarkup()}]Nitro[/] is launched!"); return Task.FromResult(ExitCodes.Success); } + + private static string ResolveUrl(Session? session) + { + if (session is null) + { + return Constants.NitroWebUrl; + } + + var defaultApiUrl = Constants.ApiUrl["https://".Length..]; + + if (session.ApiUrl == defaultApiUrl || session.ApiUrl == Constants.ApiUrl) + { + return Constants.NitroWebUrl; + } + + var baseUrl = session.ApiUrl.StartsWith("https://", StringComparison.OrdinalIgnoreCase) + || session.ApiUrl.StartsWith("http://", StringComparison.OrdinalIgnoreCase) + ? session.ApiUrl + : $"https://{session.ApiUrl}"; + + return $"{baseUrl.TrimEnd('/')}/ui"; + } } diff --git a/src/Nitro/CommandLine/src/CommandLine/Extensions/ServiceCollectionExtensions.cs b/src/Nitro/CommandLine/src/CommandLine/Extensions/ServiceCollectionExtensions.cs index 610f37ee100..1a1e388810b 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Extensions/ServiceCollectionExtensions.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Extensions/ServiceCollectionExtensions.cs @@ -1,3 +1,4 @@ +using ChilliCream.Nitro.CommandLine.Helpers; using ChilliCream.Nitro.CommandLine.Results; using ChilliCream.Nitro.CommandLine.Services; using ChilliCream.Nitro.CommandLine.Services.Configuration; @@ -21,6 +22,8 @@ public static IServiceCollection AddNitroServices(this IServiceCollection servic services.TryAddSingleton(); services.TryAddSingleton(); + services.TryAddSingleton(); + return services; } } diff --git a/src/Nitro/CommandLine/src/CommandLine/Helpers/Constants.cs b/src/Nitro/CommandLine/src/CommandLine/Helpers/Constants.cs index 835e085040f..44f11ae7bd9 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Helpers/Constants.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Helpers/Constants.cs @@ -4,9 +4,6 @@ internal static class Constants { public const int DefaultPrintWidth = 1_000; - // 5 Minutes - public const int DefaultTimeoutSec = 60 * 5; - public const string NitroWebUrl = "https://nitro.chillicream.com"; public const string ApiUrl = "https://api.chillicream.com"; diff --git a/src/Nitro/CommandLine/src/CommandLine/Helpers/IBrowserLauncher.cs b/src/Nitro/CommandLine/src/CommandLine/Helpers/IBrowserLauncher.cs new file mode 100644 index 00000000000..165dbe638d9 --- /dev/null +++ b/src/Nitro/CommandLine/src/CommandLine/Helpers/IBrowserLauncher.cs @@ -0,0 +1,6 @@ +namespace ChilliCream.Nitro.CommandLine.Helpers; + +internal interface IBrowserLauncher +{ + void Open(string url); +} diff --git a/src/Nitro/CommandLine/src/CommandLine/Helpers/SystemBrowserLauncher.cs b/src/Nitro/CommandLine/src/CommandLine/Helpers/SystemBrowserLauncher.cs new file mode 100644 index 00000000000..413c9b118d2 --- /dev/null +++ b/src/Nitro/CommandLine/src/CommandLine/Helpers/SystemBrowserLauncher.cs @@ -0,0 +1,6 @@ +namespace ChilliCream.Nitro.CommandLine.Helpers; + +internal sealed class SystemBrowserLauncher : IBrowserLauncher +{ + public void Open(string url) => SystemBrowser.Open(url); +} diff --git a/src/Nitro/CommandLine/src/CommandLine/Options/BaseSchemaFileOption.cs b/src/Nitro/CommandLine/src/CommandLine/Options/BaseSchemaFileOption.cs index bf69849a6c4..f18f950413f 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Options/BaseSchemaFileOption.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Options/BaseSchemaFileOption.cs @@ -6,7 +6,7 @@ public BaseSchemaFileOption() : base("--schema") { Description = "The path to the graphql file with the schema"; Required = true; - this.DefaultFileFromEnvironmentValue("SCHEMA_FILE"); + this.DefaultFileFromEnvironmentValue(EnvironmentVariables.SchemaFile); this.LegalFilePathsOnly(); } } diff --git a/src/Nitro/CommandLine/src/CommandLine/Options/EnvironmentVariables.cs b/src/Nitro/CommandLine/src/CommandLine/Options/EnvironmentVariables.cs index 231c3645397..c947f646c75 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Options/EnvironmentVariables.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Options/EnvironmentVariables.cs @@ -33,4 +33,6 @@ internal static class EnvironmentVariables public const string TreatDangerousAsBreaking = "TREAT_DANGEROUS_AS_BREAKING"; public const string AllowBreakingSchemaChanges = "ALLOW_BREAKING_SCHEMA_CHANGES"; public const string OperationsFile = "OPERATIONS_FILE"; + public const string SchemaFile = "SCHEMA_FILE"; + public const string SchemaExtensionFile = "SCHEMA_EXTENSION_FILE"; } diff --git a/src/Nitro/CommandLine/src/CommandLine/Options/ExtensionFileOption.cs b/src/Nitro/CommandLine/src/CommandLine/Options/ExtensionFileOption.cs index 2a5f055b9d4..191d4dc695a 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Options/ExtensionFileOption.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Options/ExtensionFileOption.cs @@ -6,7 +6,7 @@ public ExtensionFileOption() : base("--extension") { Description = "The path to the graphql file with the schema extension"; Required = true; - this.DefaultFileFromEnvironmentValue("SCHEMA_EXTENSION_FILE"); + this.DefaultFileFromEnvironmentValue(EnvironmentVariables.SchemaExtensionFile); this.LegalFilePathsOnly(); } } diff --git a/src/Nitro/CommandLine/src/CommandLine/Options/SchemaFileOption.cs b/src/Nitro/CommandLine/src/CommandLine/Options/SchemaFileOption.cs index 5d5ee5269c6..8c8d563cbd6 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Options/SchemaFileOption.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Options/SchemaFileOption.cs @@ -6,7 +6,7 @@ public SchemaFileOption() : base("--schema-file") { Description = "The path to the graphql file with the schema definition"; Required = true; - this.DefaultFileFromEnvironmentValue("SCHEMA_FILE"); + this.DefaultFileFromEnvironmentValue(EnvironmentVariables.SchemaFile); this.LegalFilePathsOnly(); } } diff --git a/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/CommandTestBase.cs b/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/CommandTestBase.cs index d6f381d4053..633ed83f439 100644 --- a/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/CommandTestBase.cs +++ b/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/CommandTestBase.cs @@ -48,6 +48,7 @@ public abstract class CommandTestBase protected readonly Mock EnvironmentsClientMock = new(MockBehavior.Strict); protected readonly Mock StagesClientMock = new(MockBehavior.Strict); internal readonly Mock _sessionServiceMock = new(); + internal readonly Mock BrowserLauncherMock = new(); protected readonly Mock WorkspacesClientMock = new(MockBehavior.Strict); private InteractionMode _interactionMode = InteractionMode.NonInteractive; private bool _authenticated = true; @@ -225,6 +226,7 @@ private ServiceProvider BuildServices(INitroConsole console) services.Replace(ServiceDescriptor.Singleton(_fileSystemMock.Object)); services.Replace(ServiceDescriptor.Singleton(_environmentVariableProviderMock.Object)); services.Replace(ServiceDescriptor.Singleton(_sessionServiceMock.Object)); + services.Replace(ServiceDescriptor.Singleton(BrowserLauncherMock.Object)); services.Replace(ServiceDescriptor.Singleton(WorkspacesClientMock.Object)); services.Replace(ServiceDescriptor.Singleton(SchemasClientMock.Object)); services.Replace(ServiceDescriptor.Singleton(FusionConfigurationClientMock.Object)); diff --git a/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Session/LaunchCommandTests.cs b/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Session/LaunchCommandTests.cs new file mode 100644 index 00000000000..b513927d1a7 --- /dev/null +++ b/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Session/LaunchCommandTests.cs @@ -0,0 +1,95 @@ +using ChilliCream.Nitro.CommandLine.Helpers; +using Moq; + +namespace ChilliCream.Nitro.CommandLine.Tests.Commands.Session; + +public sealed class LaunchCommandTests(NitroCommandFixture fixture) : SessionCommandTestBase(fixture) +{ + [Fact] + public async Task Help_ReturnsSuccess() + { + // arrange & act + var result = await ExecuteCommandAsync( + "launch", + "--help"); + + // assert + result.AssertHelpOutput( + """ + Description: + Launch Nitro in your default browser. + + Usage: + nitro launch [options] + + Options: + -?, -h, --help Show help and usage information + + Example: + nitro launch + """); + } + + [Fact] + public async Task NoSession_OpensDefaultNitroWebUrl() + { + // arrange + SetupInteractionMode(InteractionMode.Interactive); + + // act + var result = await ExecuteCommandAsync("launch"); + + // assert + Assert.Equal(0, result.ExitCode); + BrowserLauncherMock.Verify(x => x.Open(Constants.NitroWebUrl), Times.Once); + } + + [Fact] + public async Task DefaultApiUrl_OpensDefaultNitroWebUrl() + { + // arrange + SetupInteractionMode(InteractionMode.Interactive); + SetupCustomSession(); + + // act + var result = await ExecuteCommandAsync("launch"); + + // assert + Assert.Equal(0, result.ExitCode); + BrowserLauncherMock.Verify(x => x.Open(Constants.NitroWebUrl), Times.Once); + } + + [Fact] + public async Task CustomApiUrl_OpensBaseUrlSlashUi() + { + // arrange + SetupInteractionMode(InteractionMode.Interactive); + SetupCustomSession( + apiUrl: "api.custom.com", + identityUrl: "https://id.custom.com"); + + // act + var result = await ExecuteCommandAsync("launch"); + + // assert + Assert.Equal(0, result.ExitCode); + BrowserLauncherMock.Verify(x => x.Open("https://api.custom.com/ui"), Times.Once); + } + + [Fact] + public async Task CustomApiUrlWithScheme_OpensBaseUrlSlashUi() + { + // arrange + SetupInteractionMode(InteractionMode.Interactive); + SetupCustomSession( + apiUrl: "https://api.custom.com", + identityUrl: "https://id.custom.com"); + + // act + var result = await ExecuteCommandAsync("launch"); + + // assert + Assert.Equal(0, result.ExitCode); + BrowserLauncherMock.Verify(x => x.Open("https://api.custom.com/ui"), Times.Once); + } +} diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index 961edcbef57..de83b3a1324 100644 --- a/website/src/docs/docs.json +++ b/website/src/docs/docs.json @@ -22,32 +22,74 @@ "path": "explore-the-ui", "title": "Explore the UI", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "status-bar", "title": "Status Bar" }, - { "path": "explorer", "title": "Explorer" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "status-bar", + "title": "Status Bar" + }, + { + "path": "explorer", + "title": "Explorer" + } ] }, { "path": "documents", "title": "Documents", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "operations", "title": "Operations" }, - { "path": "response", "title": "Response Pane" }, - { "path": "schema-reference", "title": "Schema Reference" }, - { "path": "schema-definition", "title": "Schema Definition" }, - { "path": "connection-settings", "title": "Connection Settings" }, - { "path": "authentication", "title": "Authentication Flows" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "operations", + "title": "Operations" + }, + { + "path": "response", + "title": "Response Pane" + }, + { + "path": "schema-reference", + "title": "Schema Reference" + }, + { + "path": "schema-definition", + "title": "Schema Definition" + }, + { + "path": "connection-settings", + "title": "Connection Settings" + }, + { + "path": "authentication", + "title": "Authentication Flows" + } ] }, { "path": "apis", "title": "APIs", "items": [ - { "path": "overview", "title": "Overview" }, - { "path": "stages", "title": "Stages" }, - { "path": "deployments", "title": "Deployments" }, - { "path": "fusion", "title": "Fusion" }, + { + "path": "overview", + "title": "Overview" + }, + { + "path": "stages", + "title": "Stages" + }, + { + "path": "deployments", + "title": "Deployments" + }, + { + "path": "fusion", + "title": "Fusion" + }, { "path": "schema-registry", "title": "Schema Registry" @@ -74,7 +116,10 @@ "path": "service-monitoring", "title": "Service Monitoring" }, - { "path": "logging", "title": "Logging" } + { + "path": "logging", + "title": "Logging" + } ] }, { @@ -98,42 +143,61 @@ "title": "CLI", "items": [ { - "path": "index", - "title": "Introduction" - }, - { - "path": "authentication", - "title": "Authentication" + "path": "installation", + "title": "Installation" }, { "path": "global-options", "title": "Global Options" }, { - "path": "automation", - "title": "Automation" - } - ] - }, - { - "path": "cli-commands", - "title": "CLI Commands", - "items": [ - { "path": "api-key", "title": "api-key" }, - { "path": "api", "title": "api" }, - { "path": "client", "title": "client" }, - { "path": "environment", "title": "environment" }, - { "path": "launch", "title": "launch" }, - { "path": "login", "title": "login" }, - { "path": "logout", "title": "logout" }, - { "path": "pat", "title": "pat" }, - { "path": "schema", "title": "schema" }, - { "path": "stage", "title": "stage" }, + "path": "session", + "title": "session" + }, + { + "path": "api", + "title": "api" + }, + { + "path": "api-key", + "title": "api-key" + }, + { + "path": "pat", + "title": "pat" + }, + { + "path": "schema", + "title": "schema" + }, { - "path": "fusion-configuration", - "title": "fusion-configuration" + "path": "client", + "title": "client" }, - { "path": "workspace", "title": "workspace" } + { + "path": "fusion", + "title": "fusion" + }, + { + "path": "mcp", + "title": "mcp" + }, + { + "path": "openapi", + "title": "openapi" + }, + { + "path": "environment", + "title": "environment" + }, + { + "path": "stage", + "title": "stage" + }, + { + "path": "workspace", + "title": "workspace" + } ] }, { @@ -144,17 +208,32 @@ "path": "integrations", "title": "Integrations", "items": [ - { "path": "express", "title": "Express Server" }, - { "path": "hot-chocolate", "title": "Hot Chocolate" } + { + "path": "express", + "title": "Express Server" + }, + { + "path": "hot-chocolate", + "title": "Hot Chocolate" + } ] }, { "path": "settings", "title": "Settings", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "themes", "title": "Themes" }, - { "path": "key-bindings", "title": "Key Bindings" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "themes", + "title": "Themes" + }, + { + "path": "key-bindings", + "title": "Key Bindings" + } ] } ] @@ -357,7 +436,10 @@ "title": "v16 (preview)", "preview": true, "items": [ - { "path": "index", "title": "Overview" }, + { + "path": "index", + "title": "Overview" + }, { "path": "get-started-with-graphql-in-net-core", "title": "Getting Started" @@ -366,106 +448,274 @@ "path": "building-a-schema", "title": "Building a Schema", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "queries", "title": "Queries" }, - { "path": "mutations", "title": "Mutations" }, - { "path": "subscriptions", "title": "Subscriptions" }, - { "path": "object-types", "title": "Object Types" }, - { "path": "scalars", "title": "Scalars" }, - { "path": "arguments", "title": "Arguments" }, - { "path": "input-object-types", "title": "Input Object Types" }, - { "path": "lists", "title": "Lists" }, - { "path": "non-null", "title": "Non-Null" }, - { "path": "enums", "title": "Enums" }, - { "path": "interfaces", "title": "Interfaces" }, - { "path": "unions", "title": "Unions" }, - { "path": "extending-types", "title": "Extending Types" }, - { "path": "directives", "title": "Directives" }, - { "path": "documentation", "title": "Documentation" }, - { "path": "versioning", "title": "Versioning" }, - { "path": "relay", "title": "Relay" }, - { "path": "dynamic-schemas", "title": "Dynamic Schemas" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "queries", + "title": "Queries" + }, + { + "path": "mutations", + "title": "Mutations" + }, + { + "path": "subscriptions", + "title": "Subscriptions" + }, + { + "path": "object-types", + "title": "Object Types" + }, + { + "path": "scalars", + "title": "Scalars" + }, + { + "path": "arguments", + "title": "Arguments" + }, + { + "path": "input-object-types", + "title": "Input Object Types" + }, + { + "path": "lists", + "title": "Lists" + }, + { + "path": "non-null", + "title": "Non-Null" + }, + { + "path": "enums", + "title": "Enums" + }, + { + "path": "interfaces", + "title": "Interfaces" + }, + { + "path": "unions", + "title": "Unions" + }, + { + "path": "extending-types", + "title": "Extending Types" + }, + { + "path": "directives", + "title": "Directives" + }, + { + "path": "documentation", + "title": "Documentation" + }, + { + "path": "versioning", + "title": "Versioning" + }, + { + "path": "relay", + "title": "Relay" + }, + { + "path": "dynamic-schemas", + "title": "Dynamic Schemas" + } ] }, { "path": "resolvers-and-data", "title": "Resolvers and Data", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "resolvers", "title": "Resolvers" }, + { + "path": "index", + "title": "Overview" + }, + { + "path": "resolvers", + "title": "Resolvers" + }, { "path": "dependency-injection", "title": "Dependency Injection" }, - { "path": "dataloader", "title": "DataLoader" }, - { "path": "pagination", "title": "Pagination" }, - { "path": "filtering", "title": "Filtering" }, - { "path": "sorting", "title": "Sorting" }, - { "path": "projections", "title": "Projections" }, + { + "path": "dataloader", + "title": "DataLoader" + }, + { + "path": "pagination", + "title": "Pagination" + }, + { + "path": "filtering", + "title": "Filtering" + }, + { + "path": "sorting", + "title": "Sorting" + }, + { + "path": "projections", + "title": "Projections" + }, { "path": "fetching-from-databases", "title": "Fetching from Databases" }, - { "path": "fetching-from-rest", "title": "Fetching from REST" } + { + "path": "fetching-from-rest", + "title": "Fetching from REST" + } ] }, { "path": "guides", "title": "Guides", "items": [ - { "path": "public-api", "title": "Building a Public API" }, - { "path": "private-api", "title": "Building a Private API" }, - { "path": "error-handling", "title": "Error Handling" }, - { "path": "schema-evolution", "title": "Schema Evolution" }, - { "path": "testing", "title": "Testing" }, - { "path": "performance", "title": "Performance" }, - { "path": "dynamic-schemas", "title": "Dynamic Schemas" }, - { "path": "mcp-adapter", "title": "MCP Adapter" }, - { "path": "openapi-adapter", "title": "OpenAPI Adapter" } + { + "path": "public-api", + "title": "Building a Public API" + }, + { + "path": "private-api", + "title": "Building a Private API" + }, + { + "path": "error-handling", + "title": "Error Handling" + }, + { + "path": "schema-evolution", + "title": "Schema Evolution" + }, + { + "path": "testing", + "title": "Testing" + }, + { + "path": "performance", + "title": "Performance" + }, + { + "path": "dynamic-schemas", + "title": "Dynamic Schemas" + }, + { + "path": "mcp-adapter", + "title": "MCP Adapter" + }, + { + "path": "openapi-adapter", + "title": "OpenAPI Adapter" + } ] }, { "path": "execution-engine", "title": "Execution Engine", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "field-middleware", "title": "Field Middleware" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "field-middleware", + "title": "Field Middleware" + } ] }, { "path": "integrations", "title": "Integrations", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "entity-framework", "title": "Entity Framework" }, - { "path": "mongodb", "title": "MongoDB" }, - { "path": "spatial-data", "title": "Spatial Data" }, - { "path": "marten", "title": "Marten" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "entity-framework", + "title": "Entity Framework" + }, + { + "path": "mongodb", + "title": "MongoDB" + }, + { + "path": "spatial-data", + "title": "Spatial Data" + }, + { + "path": "marten", + "title": "Marten" + } ] }, { "path": "server", "title": "Server", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "endpoints", "title": "Endpoints" }, - { "path": "http-transport", "title": "Transports" }, - { "path": "cache-control", "title": "Cache Control" }, - { "path": "interceptors", "title": "Interceptors" }, - { "path": "warmup", "title": "Warmup" }, - { "path": "global-state", "title": "Global State" }, - { "path": "files", "title": "File Uploads" }, - { "path": "instrumentation", "title": "Instrumentation" }, - { "path": "batching", "title": "Batching" }, - { "path": "command-line", "title": "CLI Commands" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "endpoints", + "title": "Endpoints" + }, + { + "path": "http-transport", + "title": "Transports" + }, + { + "path": "cache-control", + "title": "Cache Control" + }, + { + "path": "interceptors", + "title": "Interceptors" + }, + { + "path": "warmup", + "title": "Warmup" + }, + { + "path": "global-state", + "title": "Global State" + }, + { + "path": "files", + "title": "File Uploads" + }, + { + "path": "instrumentation", + "title": "Instrumentation" + }, + { + "path": "batching", + "title": "Batching" + }, + { + "path": "command-line", + "title": "CLI Commands" + } ] }, { "path": "performance", "title": "Performance", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "trusted-documents", "title": "Trusted Documents" }, + { + "path": "index", + "title": "Overview" + }, + { + "path": "trusted-documents", + "title": "Trusted Documents" + }, { "path": "automatic-persisted-operations", "title": "Automatic Persisted Operations" @@ -476,26 +726,68 @@ "path": "securing-your-api", "title": "Securing Your API", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "authentication", "title": "Authentication" }, - { "path": "authorization", "title": "Authorization" }, - { "path": "cost-analysis", "title": "Cost Analysis" }, - { "path": "request-limits", "title": "Request Limits" }, - { "path": "introspection", "title": "Controlling Introspection" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "authentication", + "title": "Authentication" + }, + { + "path": "authorization", + "title": "Authorization" + }, + { + "path": "cost-analysis", + "title": "Cost Analysis" + }, + { + "path": "request-limits", + "title": "Request Limits" + }, + { + "path": "introspection", + "title": "Controlling Introspection" + } ] }, { "path": "api-reference", "title": "API Reference", "items": [ - { "path": "custom-attributes", "title": "Attributes" }, - { "path": "options", "title": "Configuration Options" }, - { "path": "errors", "title": "Error Codes" }, - { "path": "extending-filtering", "title": "Extending Filtering" }, - { "path": "apollo-federation", "title": "Apollo Federation" }, - { "path": "language", "title": "Language" }, - { "path": "visitors", "title": "Visitors" }, - { "path": "executable", "title": "Executable" } + { + "path": "custom-attributes", + "title": "Attributes" + }, + { + "path": "options", + "title": "Configuration Options" + }, + { + "path": "errors", + "title": "Error Codes" + }, + { + "path": "extending-filtering", + "title": "Extending Filtering" + }, + { + "path": "apollo-federation", + "title": "Apollo Federation" + }, + { + "path": "language", + "title": "Language" + }, + { + "path": "visitors", + "title": "Visitors" + }, + { + "path": "executable", + "title": "Executable" + } ] }, { @@ -2924,10 +3216,22 @@ "path": "transports", "title": "Transports", "items": [ - { "path": "index", "title": "Overview" }, - { "path": "in-memory", "title": "InMemory" }, - { "path": "rabbitmq", "title": "RabbitMQ" }, - { "path": "postgres", "title": "PostgreSQL" } + { + "path": "index", + "title": "Overview" + }, + { + "path": "in-memory", + "title": "InMemory" + }, + { + "path": "rabbitmq", + "title": "RabbitMQ" + }, + { + "path": "postgres", + "title": "PostgreSQL" + } ] }, { @@ -2938,7 +3242,10 @@ "path": "mediator", "title": "Mediator", "items": [ - { "path": "index", "title": "Overview" }, + { + "path": "index", + "title": "Overview" + }, { "path": "pipeline-and-middleware", "title": "Pipeline & Middleware" diff --git a/website/src/docs/nitro/cli-commands/api-key.md b/website/src/docs/nitro/cli-commands/api-key.md deleted file mode 100644 index 5206725466a..00000000000 --- a/website/src/docs/nitro/cli-commands/api-key.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: API Key Management ---- - -The `nitro api-key` command provides a set of subcommands that allow you to manage API keys. - -# Create an API Key - -The `nitro api-key create` command is used to create a new API key. - -> **Important:** Use the value prefixed with `Secret:` as the API key value you pass to `nitro`. - -```shell -nitro api-key create --name "My API Key" --api-id abc123 -``` - -**Options** - -- `--name `: Specifies a name for the API key for future reference. You can set it from the environment variable `NITRO_API_KEY_NAME`. -- `--api-id `: Specifies the ID of the API for which you want to create the API key. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. -- `--workspace-id `: Specifies the ID of the workspace. If not provided, the default workspace is used. You can set it from the environment variable `NITRO_WORKSPACE_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Delete an API Key - -The `nitro api-key delete` command is used to delete an API key by its ID. - -```shell -nitro api-key delete api-key123 -``` - -**Arguments** - -- ``: Specifies the ID of the API key you want to delete. - -**Options** - -- `--force`: If provided, the command will not ask for confirmation before deleting. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# List All API Keys - -The `nitro api-key list` command is used to list all API keys of a workspace. - -```shell -nitro api-key list -``` - -**Options** - -- `--cursor `: Specifies the cursor to start the query (for pagination). Useful in non-interactive mode. You can set it from the environment variable `NITRO_CURSOR`. -- `--workspace-id `: Specifies the ID of the workspace. If not provided, the default workspace is used. You can set it from the environment variable `NITRO_WORKSPACE_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` diff --git a/website/src/docs/nitro/cli-commands/api.md b/website/src/docs/nitro/cli-commands/api.md deleted file mode 100644 index 37366d6948f..00000000000 --- a/website/src/docs/nitro/cli-commands/api.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: API Management ---- - -The `nitro api` command provides a set of subcommands that allow you to manage APIs. - -# Create an API - -The `nitro api create` command is used to create a new API. - -```shell -nitro api create --name "My API" --path "/my-api" -``` - -**Options** - -- `--name `: Specifies the name of the API. You can set it from the environment variable `NITRO_API_NAME`. -- `--path `: Specifies the path to the API. You can set it from the environment variable `NITRO_API_PATH`. -- `--workspace-id `: Specifies the ID of the workspace. If not provided, the default workspace is used. You can set it from the environment variable `NITRO_WORKSPACE_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Delete an API - -The `nitro api delete` command is used to delete an API by its ID. - -```shell -nitro api delete abc123 -``` - -**Arguments** - -- ``: Specifies the ID of the API you want to delete. - -**Options** - -- `--force`: If provided, the command will not ask for confirmation before deleting. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Set API Settings - -The `nitro api set-settings` command is used to set the settings of an API. - -```shell -nitro api set-settings abc123 --treat-dangerous-as-breaking --allow-breaking-schema-changes -``` - -**Arguments** - -- ``: Specifies the ID of the API whose settings you want to set. - -**Options** - -- `--treat-dangerous-as-breaking`: If provided, dangerous changes will be treated as breaking changes. You can set it from the environment variable `NITRO_TREAT_DANGEROUS_AS_BREAKING`. -- `--allow-breaking-schema-changes`: If provided, allows breaking schema changes when no client breaks. You can set it from the environment variable `NITRO_ALLOW_BREAKING_SCHEMA_CHANGES`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Show API Details - -The `nitro api show` command is used to show the details of an API. - -```shell -nitro api show abc123 -``` - -**Arguments** - -- ``: Specifies the ID of the API whose details you want to see. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` diff --git a/website/src/docs/nitro/cli-commands/client.md b/website/src/docs/nitro/cli-commands/client.md deleted file mode 100644 index 0a36e7e88af..00000000000 --- a/website/src/docs/nitro/cli-commands/client.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Client Management ---- - -The `nitro client` command provides a set of subcommands that allow you to create, delete, upload, validate, publish, unpublish client versions, as well as list all clients of an API, show details of a specific client, and download queries from a stage. - -# Create a Client - -The `nitro client create` command is used to create a new client. - -```shell -nitro client create --api-id abc123 --name "My Client" -``` - -**Options** - -- `--api-id `: Specifies the ID of the API for which you want to create a client. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. -- `--name `: Specifies a name for the client for future reference. You can set it from the environment variable `NITRO_API_KEY_NAME`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Delete a Client - -The `nitro client delete` command is used to delete a client by its ID. - -```shell -nitro client delete client123 -``` - -**Arguments** - -- ``: Specifies the ID of the client you want to delete. - -**Options** - -- `--force`: If provided, the command will not ask for confirmation before deleting. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Upload a Client Version - -The `nitro client upload` command is used to upload a new client version. - -```shell -nitro client upload --tag v1.0.1 --operations-file ./operations.json --client-id client123 -``` - -**Options** - -- `--tag ` **(required)**: Specifies the tag of the client version to upload. It creates a new version of the client with the specified tag. The tag can be any string, but it's recommended to use a version number (e.g., v1.0.1) or a commit hash. You can set it from the environment variable `NITRO_TAG`. -- `--operations-file ` **(required)**: Specifies the path to the JSON file with the operations. This is a file containing persisted queries in Relay style. You can set it from the environment variable `NITRO_OPERATIONS_FILE`. -- `--client-id ` **(required)**: Specifies the ID of the client. This ID can be retrieved with the `nitro client list` command. You can set it from the environment variable `NITRO_CLIENT_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Validate a Client Version - -The `nitro client validate` command is used to validate a client version. - -```shell -nitro client validate --stage production --client-id client123 --operations-file ./operations.json -``` - -**Options** - -- `--stage ` **(required)**: Specifies the name of the stage. This is the name of the environment where the client will be validated. You can set it from the environment variable `NITRO_STAGE`. -- `--client-id ` **(required)**: Specifies the ID of the client. You can set it from the environment variable `NITRO_CLIENT_ID`. -- `--operations-file ` **(required)**: Specifies the path to the JSON file with the operations. You can set it from the environment variable `NITRO_OPERATIONS_FILE`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Publish a Client Version - -The `nitro client publish` command is used to publish a client version to a stage. - -```shell -nitro client publish --tag v1.0.0 --stage production --client-id client123 -``` - -**Options** - -- `--tag ` **(required)**: Specifies the tag of the client version to publish. You can set it from the environment variable `NITRO_TAG`. -- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. -- `--client-id ` **(required)**: Specifies the ID of the client. You can set it from the environment variable `NITRO_CLIENT_ID`. -- `--force`: If provided, the command will not ask for confirmation before publishing. -- `--wait-for-approval`: If provided, waits for a user to approve the schema change in case of a breaking change. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Unpublish a Client Version - -The `nitro client unpublish` command is used to unpublish a client version from a stage. - -```shell -nitro client unpublish --tag v1.0.0 --stage production --client-id client123 -``` - -**Options** - -- `--tag ` **(required)**: Specifies the tag of the client version to unpublish. You can set it from the environment variable `NITRO_TAG`. -- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. -- `--client-id ` **(required)**: Specifies the ID of the client. You can set it from the environment variable `NITRO_CLIENT_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Download Queries from a Stage - -The `nitro client download` command is used to download the queries from a stage. - -```shell -nitro client download --api-id abc123 --stage production --output ./queries --format relay -``` - -**Options** - -- `--api-id ` **(required)**: Specifies the ID of the API from which to download the queries. You can set it from the environment variable `NITRO_API_ID`. -- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. -- `--output ` **(required)**: Specifies the path where the queries will be stored. -- `--format `: Specifies the format in which the queries will be stored. Options are `folder` or `relay`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# List All Clients - -The `nitro client list` command is used to list all clients of an API. - -```shell -nitro client list --api-id abc123 -``` - -**Options** - -- `--api-id `: Specifies the ID of the API for which you want to list the clients. You can set it from the environment variable `NITRO_API_ID`. -- `--cursor `: Specifies the cursor to start the query (for pagination). You can set it from the environment variable `NITRO_CURSOR`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Show Client Details - -The `nitro client show` command is used to show details of a specific client. - -```shell -nitro client show client123 --fields publishedVersions,versions -``` - -**Arguments** - -- ``: The ID of the client whose details you want to show. - -**Options** - -- `--fields `: Specifies additional fields to display in the client detail prompt. You can specify multiple fields separated by commas. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` diff --git a/website/src/docs/nitro/cli-commands/environment.md b/website/src/docs/nitro/cli-commands/environment.md deleted file mode 100644 index c7838e7a0b5..00000000000 --- a/website/src/docs/nitro/cli-commands/environment.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Environment ---- - -The `nitro environment` command provides a set of subcommands that allow you to manage environments. - -# Create an Environment - -The `nitro environment create` command is used to create a new environment. - -```shell -nitro environment create --name "Development Environment" -``` - -**Options** - -- `--name ` or `-n `: Specifies the name of the environment. -- `--workspace-id `: Specifies the ID of the workspace. You can set it from the environment variable `NITRO_WORKSPACE_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Show Environment Details - -The `nitro environment show` command is used to show the details of an environment. - -```shell -nitro environment show env123 -``` - -**Arguments** - -- ``: Specifies the ID of the environment whose details you want to see. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` diff --git a/website/src/docs/nitro/cli-commands/fusion-configuration.md b/website/src/docs/nitro/cli-commands/fusion-configuration.md deleted file mode 100644 index 1d6c797affa..00000000000 --- a/website/src/docs/nitro/cli-commands/fusion-configuration.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Fusion Configuration Management ---- - -# Fusion Configuration Publish - -The `nitro fusion-configuration publish` command provides a set of subcommands that allow you to begin, start, validate, cancel, and commit a fusion configuration publish, facilitating the management and deployment of fusion configurations. - -## Begin a Configuration Publish - -The `nitro fusion-configuration publish begin` command requests a deployment slot to begin the publish process of a fusion configuration. - -```shell -nitro fusion-configuration publish begin \ - --tag \ - --stage \ - --api-id \ - [--subgraph-id ] \ - [--subgraph-name ] \ - [--wait-for-approval] \ - [--api-key ] -``` - -**Options:** - -- `--tag ` **(required)**: Specifies the tag of the schema version to deploy. You can set it from the environment variable `NITRO_TAG`. - -- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. - -- `--api-id ` **(required)**: Specifies the ID of the API. You can set it from the environment variable `NITRO_API_ID`. - -- `--subgraph-id `: Specifies the ID of the subgraph. You can set it from the environment variable `NITRO_SUBGRAPH_ID`. - -- `--subgraph-name `: Specifies the name of the subgraph. You can set it from the environment variable `NITRO_SUBGRAPH_NAME`. - -- `--wait-for-approval`: Waits for a user to approve the schema change in the app in case of a breaking change. - -- `--api-key `: Specifies the API key used for authentication. You can set it from the environment variable `NITRO_API_KEY`. - -## Start a Fusion Configuration Publish - -The `nitro fusion-configuration publish start` command initiates the publish process of a fusion configuration. -This command has to be executed just after the completion of the `begin` command to confirm the deployment slot. - -```shell -nitro fusion-configuration publish start \ - --request-id \ - [--api-key ] -``` - -**Options:** - -- `--request-id `: Specifies the ID of the request. You do not have to provide this when you executed the `begin` command in the same session. - -- `--api-key `: Specifies the API key used for authentication. You can set it from the environment variable `NITRO_API_KEY`. - -## Validate a Fusion Configuration - -The `nitro fusion-configuration publish validate` command validates a fusion configuration against the schema and clients. -This step is optional and can be used to ensure that the configuration is correct before committing the publish. - -```shell -nitro fusion-configuration publish validate \ - --request-id \ - --configuration \ - [--api-key ] -``` - -**Options:** - -- `--request-id `: Specifies the ID of the request. You do not have to provide this when you executed the `begin` command in the same session. - -- `--configuration ` **(required)**: Specifies the path to the fusion configuration file. You can set it from the environment variable `NITRO_FUSION_CONFIG_FILE`. - -- `--api-key `: Specifies the API key used for authentication. You can set it from the environment variable `NITRO_API_KEY`. - -## Commit a Fusion Configuration Publish - -The `nitro fusion-configuration publish commit` command commits the publish process of a fusion configuration. - -```shell -nitro fusion-configuration publish commit \ - --request-id \ - --configuration \ - [--api-key ] -``` - -**Options:** - -- `--request-id `: Specifies the ID of the request. You do not have to provide this when you executed the `begin` command in the same session. - -- `--configuration ` **(required)**: Specifies the path to the fusion configuration file. You can set it from the environment variable `NITRO_FUSION_CONFIG_FILE`. - -- `--api-key `: Specifies the API key used for authentication. You can set it from the environment variable `NITRO_API_KEY`. - -## Cancel a Fusion Configuration Publish - -The `nitro fusion-configuration publish cancel` command cancels the publish process of a fusion configuration. - -```shell -nitro fusion-configuration publish cancel \ - --request-id \ - [--api-key ] -``` - -**Options:** - -- `--request-id `: Specifies the ID of the request. You do not have to provide this when you executed the `begin` command in the same session. - -- `--api-key `: Specifies the API key used for authentication. You can set it from the environment variable `NITRO_API_KEY`. - -# Download the Most Recent Gateway Configuration - -The `nitro fusion-configuration download` command is used to download the most recent gateway configuration. - -```shell -nitro fusion-configuration download \ - --stage \ - --api-id \ - [--output-file ] \ - [--api-key ] -``` - -**Options:** - -- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. - -- `--api-id ` **(required)**: Specifies the ID of the API. You can set it from the environment variable `NITRO_API_ID`. - -- `--output-file `: Specifies the path and name of the output file where the downloaded configuration will be saved. You can set it from the environment variable `NITRO_OUTPUT_FILE`. - -- `--api-key `: Specifies the API key used for authentication. It's required if you are not logged in. You can set it from the environment variable `NITRO_API_KEY`. diff --git a/website/src/docs/nitro/cli-commands/launch.md b/website/src/docs/nitro/cli-commands/launch.md deleted file mode 100644 index 9ca83354edd..00000000000 --- a/website/src/docs/nitro/cli-commands/launch.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nitro Launch ---- - -The `nitro launch` command is used to launch Nitro in your default web browser. This provides an easy and immediate way to start using the interactive interface of Nitro without needing to manually open it. - -To use the `nitro launch` command, simply type it in your terminal: - -```shell -nitro launch -``` diff --git a/website/src/docs/nitro/cli-commands/login.md b/website/src/docs/nitro/cli-commands/login.md deleted file mode 100644 index 60ea9c96f86..00000000000 --- a/website/src/docs/nitro/cli-commands/login.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Login ---- - -The `nitro login` command is used to log into your user account on Nitro CLI. On execution, Nitro CLI attempts to launch a web browser to facilitate an interactive login process. This allows you to authenticate with your credentials and provides a seamless link between the command-line interface and the web-based management console. - -To use the `nitro login` command, type it into your terminal as shown below: - -```shell -nitro login -``` - -This command does not require any specific arguments or options for basic execution. After running the command, follow the prompts in the newly launched web browser to complete the login process. diff --git a/website/src/docs/nitro/cli-commands/logout.md b/website/src/docs/nitro/cli-commands/logout.md deleted file mode 100644 index b3b74afea7f..00000000000 --- a/website/src/docs/nitro/cli-commands/logout.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Logout ---- - -The `nitro logout` command is used to log out of your user account on Nitro CLI. - -To use the `nitro logout` command, type it into your terminal as shown below: - -```shell -nitro logout -``` - -This command does not require any specific arguments or options for basic execution. After running the command, you will be logged out of your current session. diff --git a/website/src/docs/nitro/cli-commands/pat.md b/website/src/docs/nitro/cli-commands/pat.md deleted file mode 100644 index 2a2a88d6179..00000000000 --- a/website/src/docs/nitro/cli-commands/pat.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Personal Access Token Management ---- - -The `nitro pat` command provides a set of subcommands that allow you to manage Personal Access Tokens (PATs). PATs are tokens associated with your user account that can be used for authenticating with the Nitro platform in scripts, automation tools, and CI/CD pipelines. - -# Create a Personal Access Token - -> **Important:** Use the value prefixed with `Secret:` as the API key value you pass to `nitro`. - -The `nitro pat create` command is used to create a new personal access token. - -```shell -nitro pat create --description "Automation Token" --expires 180 -``` - -**Options** - -- `--description `: Provides a description for the PAT to help you identify it later. You can set it from the environment variable `NITRO_DESCRIPTION`. -- `--expires `: Specifies the expiration time of the PAT in days. The default is 180 days. You can set it from the environment variable `NITRO_EXPIRES`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -## List All Personal Access Tokens - -The `nitro pat list` command is used to list all personal access tokens associated with your account. - -```shell -nitro pat list -``` - -**Options** - -- `--cursor `: Specifies the cursor to start the query (for pagination). Useful in non-interactive mode. You can set it from the environment variable `NITRO_CURSOR`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -### Revoke a Personal Access Token - -The `nitro pat revoke` command is used to revoke a personal access token by its ID. - -```shell -nitro pat revoke UGVyc29uYWxBY2Nlc3NUb2tlbjpUaGlzIElzIE5vdCBBIFRva2VuIDspIA== -``` - -**Arguments** - -- ``: Specifies the ID of the personal access token you want to revoke. - -**Options** - -- `--force`: If provided, the command will not ask for confirmation before revoking. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` diff --git a/website/src/docs/nitro/cli-commands/schema.md b/website/src/docs/nitro/cli-commands/schema.md deleted file mode 100644 index 310072ba169..00000000000 --- a/website/src/docs/nitro/cli-commands/schema.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Schema Management ---- - -The `nitro schema` command provides a set of subcommands that allow you to upload, validate, and publish schemas. - -# Publish a Schema - -The `nitro schema publish` command is used to publish a schema version to a stage. - -```shell -nitro schema publish \ - --tag v1.0.0 \ - --stage production \ - --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== -``` - -**Options** - -- `--tag ` **(required)**: Specifies the tag of the schema version to deploy. It creates a new version of the schema with the specified tag. The tag can be any string, but it's recommended to use a version number (e.g., v1, v2) or a commit hash. You can set it from the environment variable `NITRO_TAG`. -- `--stage ` **(required)**: Specifies the name of the stage. This is the name of the environment where the schema will be published. You can set it from the environment variable `NITRO_STAGE`. -- `--api-id ` **(required)**: Specifies the ID of the API to which you are uploading the schema. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. -- `--force`: Forces the operation to succeed even if there are errors. -- `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. -- `--wait-for-approval`: Waits for a user to approve the schema change in the app in case of a breaking change. - -# Validate a Schema - -The `nitro schema validate` command is used to validate a new client version. - -```shell -nitro schema validate \ - --stage development \ - --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== \ - --schema-file /path/to/your/schema.graphql -``` - -**Options** - -- `--stage ` **(required)**: Specifies the name of the stage. This is the name of the environment where the schema will be validated. You can set it from the environment variable `NITRO_STAGE`. -- `--api-id ` **(required)**: Specifies the ID of the API against which the schema will be validated. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. -- `--schema-file ` **(required)**: Specifies the path to the GraphQL SDL schema file to be validated. You can set it from the environment variable `NITRO_SCHEMA_FILE`. -- `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. - -# Upload a Schema - -The `nitro schema upload` command is used to upload a new schema version. - -```shell -nitro schema upload \ - --tag v1.0.0 \ - --schema-file /path/to/your/schema.graphql \ - --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== -``` - -**Options** - -- `--tag ` **(required)**: Specifies the tag of the schema version to deploy. It creates a new version of the schema with the specified tag. The tag can be any string, but it's recommended to use a version number (e.g., v1, v2) or a commit hash. You can set it from the environment variable `NITRO_TAG`. -- `--schema-file ` **(required)**: Specifies the path to the GraphQL SDL schema file to be uploaded. This should be a .graphql file containing the schema definition. You can set it from the environment variable `NITRO_SCHEMA_FILE`. - -- `--api-id ` **(required)**: Specifies the ID of the API to which you are uploading the schema. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. - -- `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. - -# Download a Schema - -The `nitro schema download` command is used to download a schema from a stage. - -```shell -nitro schema download --api-id abc123 --stage production --file ./schema.graphql -``` - -**Options** - -- `--api-id ` **(required)**: Specifies the ID of the API from which to download the schema. You can set it from the environment variable `NITRO_API_ID`. -- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. -- `--file ` **(required)**: Specifies the file path where the schema will be stored. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - - diff --git a/website/src/docs/nitro/cli-commands/stage.md b/website/src/docs/nitro/cli-commands/stage.md deleted file mode 100644 index 8a128d4ede6..00000000000 --- a/website/src/docs/nitro/cli-commands/stage.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Stage Management ---- - -The `nitro stage` command provides a set of subcommands that allow you to manage stages. - -# Edit Stages of an API - -The `nitro stage edit` command provides an interactive user interface for managing the stages of an API. The screen you see allows you to add new stages, save changes, edit existing stages, and delete stages. - -```shell -nitro stage edit \ - --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== # optional -``` - -```shell - - Edit the stages of api QX... in your/Workspace - - ┌─────────┬─────────────┬─────────┐ - │ Name │ DisplayName │ After │ - ├─────────┼─────────────┼─────────┤ - │ dev │ Development │ │ - │ prod │ Production │ dev │ - └─────────┴─────────────┴─────────┘ - (a)dd new stage - (s)ave changes - press (e) to edit / press (d) to delete -``` - -The Console UI displays a table with the following columns: - -- **Name**: The unique identifier of the stage. -- **DisplayName**: The user-friendly name that is shown in the UI. -- **After**: The stage that the current stage follows. - -Below the table, you'll find several options to manage stages: - -- **(a)dd new stage**: This option allows you to add a new stage to the API. -- **(s)ave changes**: This option saves any changes you've made to the stages. -- **(e)dit**: This option allows you to edit an existing stage. -- **(d)elete**: This option allows you to delete a stage. - -**Hot to use the Console UI** - -1. **Navigate**: Use the arrow keys on your keyboard to navigate through the table of stages. -2. **Add a new stage**: To add a new stage, press the 'a' key on your keyboard. You'll be prompted to enter the details of the new stage. -3. **Save changes**: To save any changes you've made to the stages, press the 's' key on your keyboard. -4. **Edit a stage**: To edit an existing stage, use the arrow keys to select the stage you want to edit, then press the 'e' key. You'll be prompted to update the stage's details. -5. **Delete a stage**: To delete a stage, use the arrow keys to select the stage you want to delete, then press the 'd' key. You'll be asked to confirm your decision before the stage is deleted. - -Remember to save any changes you've made before exiting the Console UI. - -**Options:** - -- `--api-id `: Specifies the ID of the API for which you want to edit stages. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. - -# Edit Stages of an API (non-interactive) - -The `nitro stage edit` command also provides a non-interactive user interface for managing the stages of an API. - -```shell -nitro stage edit --api-id abc123 --configuration '[{"Name":"stage1","DisplayName":"Stage 1","Conditions":[{"AfterStage":"stage2"}]}]' -``` - -**Options** - -- `--api-id `: Specifies the ID of the API for which you want to edit stages. You can set it from the environment variable `NITRO_API_ID`. -- `--configuration `: Provides the stage configuration in JSON format. If not provided, an interactive selection will be shown. The input should be a JSON array of stage configurations. - -**Example Configuration:** - -```json -[ - { - "Name": "stage1", - "DisplayName": "Stage 1", - "Conditions": [ - { - "AfterStage": "stage2" - } - ] - } -] -``` - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# List All Stages - -The `nitro stage list` command is used to list all stages of an API. - -```shell -nitro stage list --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== -``` - -**Options** - -- `--api-id `: Specifies the ID of the API for which you want to list the stages. You can set it from the environment variable `NITRO_API_ID`. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - - diff --git a/website/src/docs/nitro/cli-commands/workspace.md b/website/src/docs/nitro/cli-commands/workspace.md deleted file mode 100644 index a6f53587799..00000000000 --- a/website/src/docs/nitro/cli-commands/workspace.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Workspace Management ---- - -The `nitro workspace` command provides a set of subcommands that allow you to manage workspaces. - -# Create a Workspace - -The `nitro workspace create` command is used to create a new workspace. - -```shell -nitro workspace create --name "My Workspace" --default -``` - -**Options** - -- `--name `: Specifies the name of the workspace. -- `--default`: If provided, sets the created workspace as the default workspace. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Set Default Workspace - -The `nitro workspace set-default` command is used to select a workspace and set it as your default workspace. - -```shell -nitro workspace set-default -``` - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# List all Workspaces - -The `nitro workspace list` command is used to list all workspaces. - -```shell -nitro workspace list -``` - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Show Workspace Details - -The `nitro workspace show` command is used to show the details of a workspace. - -```shell -nitro workspace show abc123 -``` - -**Arguments:** - -- ``: Specifies the ID of the workspace whose details you want to see. - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` - -# Show Current Workspace - -The `nitro workspace current` command is used to show the name of the currently selected workspace. - -```shell -nitro workspace current -``` - -**Global Options** - -- `--cloud-url ` -- `--api-key ` -- `--output ` diff --git a/website/src/docs/nitro/cli/api-key.md b/website/src/docs/nitro/cli/api-key.md new file mode 100644 index 00000000000..a5627532479 --- /dev/null +++ b/website/src/docs/nitro/cli/api-key.md @@ -0,0 +1,101 @@ +--- +title: api-key +--- + +The `nitro api-key` commands manage API keys. API keys authenticate non-interactive use of the CLI and the Nitro server, and are intended for CI/CD pipelines, deployments, and telemetry reporting from your GraphQL server. + +A key is scoped either to a single API (via `--api-id`) or to an entire workspace (via `--workspace-id`). API-scoped keys can only operate on the API they were created for, workspace-scoped keys can operate on every API in the workspace. + +Optionally, an API key can additionally be restricted to a single stage with the `--stage-condition` option. This lets you issue, for example, a `dev`-only key that cannot publish to `prod`. + +> If you need broader, user-level access (for example to automate workspace administration), use a [Personal Access Token](/docs/nitro/cli/pat) instead. + +All `api-key` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro api-key create` + +Create a new API key. The secret is returned only once at creation time, store it in a secure location (for example a secret manager or a CI secret) before closing the terminal. + +```shell +nitro api-key create \ + --name "" \ + --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `--name ` | `NITRO_API_KEY_NAME` | Display name for the API key, used for later reference. Required. | +| `--api-id ` | `NITRO_API_ID` | ID of the API to scope the key to. Required unless `--workspace-id` is set. Get the ID from `nitro api list` or the API overview page in the Nitro UI. | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace to scope the key to. Falls back to the workspace from the current session. Required unless `--api-id` is set. | +| `--stage-condition ` | | _(Preview)_ Restrict the key to a single stage by name. If omitted, the key is valid for all stages. | + +When run interactively without `--api-id` or `--workspace-id`, the CLI prompts you to pick between an API-scoped or workspace-scoped key. + +## Examples + +Create an API-scoped key: + +```shell +nitro api-key create --name "" --api-id "" +``` + +Create a workspace-scoped key with an explicit workspace: + +```shell +nitro api-key create --name "" --workspace-id "" +``` + +Restrict a key to a single stage: + +```shell +nitro api-key create \ + --name "" \ + --api-id "" \ + --stage-condition "" +``` + +Capture the secret in a script: + +```shell +SECRET=$(nitro api-key create \ + --name "" \ + --api-id "" \ + --output json | jq -r '.secret') +``` + +# `nitro api-key list` + +List the API keys in a workspace. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro api-key list +``` + +## Options + +| Option | Env | Description | +| ------------------------------- | -------------------- | -------------------------------------------------------------------------- | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace. Falls back to the workspace from the current session. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro api-key delete` + +Delete an API key by its ID. Once deleted, any client using the key loses access immediately. + +```shell +nitro api-key delete "" +``` + +## Arguments + +| Argument | Description | +| -------- | -------------------------------------- | +| `` | ID of the API key to delete. Required. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/api.md b/website/src/docs/nitro/cli/api.md new file mode 100644 index 00000000000..5d34d45686e --- /dev/null +++ b/website/src/docs/nitro/cli/api.md @@ -0,0 +1,146 @@ +--- +title: api +--- + +The `nitro api` commands manage APIs in a workspace. + +Each API has a kind that determines how it behaves: `service` for a single GraphQL service, `gateway` for a federated gateway, or `collection` for grouping related APIs together. + +All `api` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro api create` + +Create a new API in a workspace. The path must start with `/` and uniquely identifies the API within its workspace. + +```shell +nitro api create \ + --name "" \ + --path "" +``` + +## Options + +| Option | Env | Description | +| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------- | +| `--name ` | `NITRO_API_NAME` | The name of the API. Required. | +| `--path ` | `NITRO_API_PATH` | The path to the API. Must start with `/`. Required. | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace to create the API in. Falls back to the workspace from the current session. | +| `--kind ` | `NITRO_API_KIND` | The kind of the API. One of `collection`, `gateway`, `service`. | + +## Examples + +Create an API in the workspace from the current session: + +```shell +nitro api create --name "" --path "/products" +``` + +Create an API in an explicit workspace: + +```shell +nitro api create \ + --name "" \ + --path "/products" \ + --workspace-id "" +``` + +Create a gateway API: + +```shell +nitro api create \ + --name "" \ + --path "/products/catalog" \ + --kind gateway +``` + +# `nitro api list` + +List all APIs in a workspace. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro api list +``` + +## Options + +| Option | Env | Description | +| ------------------------------- | -------------------- | -------------------------------------------------------------------------- | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace. Falls back to the workspace from the current session. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro api show` + +Show the details of a single API by its ID. + +```shell +nitro api show "" +``` + +## Arguments + +| Argument | Description | +| -------- | -------------------------------- | +| `` | ID of the API to show. Required. | + +# `nitro api set-settings` + +Update the schema registry settings of an API. These settings control how breaking and dangerous schema changes are evaluated when publishing new schema versions. + +```shell +nitro api set-settings "" \ + --treat-dangerous-as-breaking \ + --allow-breaking-schema-changes +``` + +## Arguments + +| Argument | Description | +| -------- | ---------------------------------- | +| `` | ID of the API to update. Required. | + +## Options + +| Option | Env | Description | +| --------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `--treat-dangerous-as-breaking` | `NITRO_TREAT_DANGEROUS_AS_BREAKING` | Treat dangerous schema changes as breaking. Required when running non-interactively. | +| `--allow-breaking-schema-changes` | `NITRO_ALLOW_BREAKING_SCHEMA_CHANGES` | Allow breaking schema changes when no published client breaks. Required when running non-interactively. | + +When run interactively, the CLI prompts for any setting you omit. + +## Examples + +Treat dangerous changes as breaking and reject any breaking change: + +```shell +nitro api set-settings "" \ + --treat-dangerous-as-breaking true \ + --allow-breaking-schema-changes false +``` + +Allow breaking changes when no client is affected: + +```shell +nitro api set-settings "" \ + --treat-dangerous-as-breaking true \ + --allow-breaking-schema-changes true +``` + +# `nitro api delete` + +Delete an API by its ID. This removes the API and all of its schema versions, clients, and stages. + +```shell +nitro api delete "" +``` + +## Arguments + +| Argument | Description | +| -------- | ---------------------------------- | +| `` | ID of the API to delete. Required. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/authentication.md b/website/src/docs/nitro/cli/authentication.md deleted file mode 100644 index 4679fe6d3f4..00000000000 --- a/website/src/docs/nitro/cli/authentication.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Authentication ---- - -Nitro CLI offers two methods for authenticating your account: interactive login and API key authentication. - -# Interactive Login - -To initiate the interactive login process, use the `nitro login` command. This command opens a browser window where you can sign in using your preferred login provider. - -```shell -nitro login -``` - -Once logged in, you will be asked to select your default workspace. If you don't have a default workspace yet, go to [nitro.chillicream.com](https://nitro.chillicream.com) and sign in there. Upon signing in, a workspace will automatically be created for you. - -> You can quickly navigate to the Nitro site using the `nitro launch` command. - -After you have selected your workspace, your setup is complete and you're ready to start using Nitro CLI. - -# API Key Authentication - -The second method for authentication is via API keys. API keys are unique identifiers that grant access to your workspace without the need for interactive login. They are useful for automating tasks or for use in a Continuous Integration/Continuous Deployment (CI/CD) pipeline. - -You can use the `api-key` subcommand in Nitro CLI to manage your API keys. How you can manage the api keys, you can read in the [API Key Management](/docs/nitro/cli-commands/api-key) section. -Remember to keep your API keys secure, as they provide full access to your workspace. If an API key is compromised, make sure to delete it and create a new one. diff --git a/website/src/docs/nitro/cli/automation.md b/website/src/docs/nitro/cli/automation.md deleted file mode 100644 index 81c5f50dbaa..00000000000 --- a/website/src/docs/nitro/cli/automation.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Automation ---- - -When integrating the `nitro` CLI into CI/CD pipelines or automation scripts, you can use API keys or personal access tokens (PATs) for authentication. - -- **API Keys**: Ideal for use in CI/CD or for telemetry reporting in your GraphQL server. You can create API keys with the `nitro api-key create` command. - -- **Personal Access Tokens (PATs)**: If you need to automate other tasks or require broader access, you can use personal access tokens. Create them with the `nitro pat create` command. Use the PAT in the CLI with the `--api-key` option. - -# Passing Inputs Non-Interactively - -All inputs in the CLI can be passed via environment variables or as options in the CLI commands. This allows you to skip the interactive mode and use the CLI non-interactively in your automation scripts. - -For example: - -- Use environment variables like `NITRO_API_ID`, `NITRO_STAGE`, etc., to provide inputs. -- Use command-line options like `--api-id`, `--stage`, etc., to specify inputs directly. - -# Parsing CLI Output - -By default, the CLI outputs rich text suitable for human reading. When using the CLI in automation scripts, you may want to parse the output programmatically. - -- Use the `--output json` option to get the output in JSON format. This allows you to easily parse the output using tools like `jq`. - -Example: - -```shell -nitro api-key list --output json | jq '.' -``` diff --git a/website/src/docs/nitro/cli/client.md b/website/src/docs/nitro/cli/client.md new file mode 100644 index 00000000000..4d7460cc350 --- /dev/null +++ b/website/src/docs/nitro/cli/client.md @@ -0,0 +1,302 @@ +--- +title: client +--- + +The `nitro client` commands manage clients of an API. A client is a registered consumer of a GraphQL API (for example a web app, a mobile app, or another service) along with the set of operations it sends. + +A client owns a sequence of versions, each identified by a tag and containing a set of persisted operations. Versions are published to a stage to mark them as live. + +All `client` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro client create` + +Create a new client under an API. + +```shell +nitro client create \ + --name "" \ + --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `--name ` | `NITRO_CLIENT_NAME` | Display name of the client. Required. | +| `--api-id ` | `NITRO_API_ID` | ID of the API the client belongs to. Required when no workspace is set in the session. Get the ID from `nitro api list` or the Nitro UI. | + +## Examples + +Create a client interactively (prompts for missing values): + +```shell +nitro client create +``` + +Create a client non-interactively: + +```shell +nitro client create --name "" --api-id "" +``` + +# `nitro client upload` + +Upload a new client version with the operations the client sends. The version is identified by a tag and is not yet published to any stage. + +```shell +nitro client upload \ + --client-id "" \ + --tag "" \ + --operations-file +``` + +## Options + +| Option | Env | Description | +| ------------------------------------- | ----------------------- | -------------------------------------------------------------------------- | +| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the new client version, for example `v1` or a Git commit. Required. | +| `--operations-file ` | `NITRO_OPERATIONS_FILE` | Path to the JSON file with the persisted operations. Required. | + +## Examples + +Upload a client version: + +```shell +nitro client upload \ + --client-id "" \ + --tag "v1" \ + --operations-file ./operations.json +``` + +# `nitro client publish` + +Publish a previously uploaded client version to a stage. The version is identified by its tag. + +```shell +nitro client publish \ + --client-id "" \ + --tag "" \ + --stage "" +``` + +## Options + +| Option | Env | Description | +| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the client version to publish. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to publish to. Required. | +| `--force` | | Skip confirmation prompts and publish even when the version contains breaking operations. Mutually exclusive with `--wait-for-approval`. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Block the command until a reviewer approves the deployment. Mutually exclusive with `--force`. Required when the stage gates deployments. | + +## Examples + +Publish to `dev`: + +```shell +nitro client publish \ + --client-id "" \ + --tag "v1" \ + --stage "dev" +``` + +Publish to a gated stage and wait for approval: + +```shell +nitro client publish \ + --client-id "" \ + --tag "v1" \ + --stage "production" \ + --wait-for-approval +``` + +# `nitro client validate` + +Validate a new client version against a stage without publishing it. Run this in your pull request validation workflow to catch breaking operations before they are merged. + +```shell +nitro client validate \ + --client-id "" \ + --stage "" \ + --operations-file +``` + +## Options + +| Option | Env | Description | +| ------------------------------------- | ----------------------- | -------------------------------------------------------------- | +| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to validate against. Required. | +| `--operations-file ` | `NITRO_OPERATIONS_FILE` | Path to the JSON file with the persisted operations. Required. | + +## Examples + +Validate against the `dev` stage: + +```shell +nitro client validate \ + --client-id "" \ + --stage "dev" \ + --operations-file ./operations.json +``` + +# `nitro client unpublish` + +Unpublish one or more client version tags from a stage. The version is not deleted, only removed from the stage. + +```shell +nitro client unpublish \ + --client-id "" \ + --stage "" \ + --tag "" +``` + +## Options + +| Option | Env | Description | +| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | +| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to unpublish from. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the client version to unpublish. Pass multiple times to unpublish several tags. Required. | + +## Examples + +Unpublish a single tag: + +```shell +nitro client unpublish \ + --client-id "" \ + --stage "dev" \ + --tag "" +``` + +Unpublish multiple tags in one call: + +```shell +nitro client unpublish \ + --client-id "" \ + --stage "dev" \ + --tag "v1" \ + --tag "v2" +``` + +# `nitro client download` + +Download all persisted operations of the client currently published to a stage. Writes either a single JSON file (Relay-style) or a directory with one `.graphql` file per operation. + +```shell +nitro client download \ + --api-id "" \ + --stage "" \ + --path +``` + +## Options + +| Option | Env | Description | +| ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to download from. Required. | +| `--path ` | | Path to write the operations to. A file path for `relay`, a directory for `folder`. Required. | +| `--format ` | | Output format. `relay` writes a single JSON map of `id -> operation`, `folder` writes one file per operation. Defaults to `relay`. | + +## Examples + +Download Relay-style persisted operations: + +```shell +nitro client download \ + --api-id "" \ + --stage "dev" \ + --path ./operations.json +``` + +Download as a folder of `.graphql` files: + +```shell +nitro client download \ + --api-id "" \ + --stage "dev" \ + --path ./operations \ + --format folder +``` + +# `nitro client list` + +List all clients of an API. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro client list --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | -------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required when running non-interactively. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro client list versions` + +List all versions of a client, including ones that have never been published to a stage. + +```shell +nitro client list versions --client-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------------- | ----------------- | -------------------------------------------------------------------- | +| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required when running non-interactively. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro client list published-versions` + +List only the versions of a client that are currently published to at least one stage. + +```shell +nitro client list published-versions --client-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------------- | ----------------- | -------------------------------------------------------------------- | +| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required when running non-interactively. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro client show` + +Show the details of a single client by its ID. + +```shell +nitro client show "" +``` + +## Arguments + +| Argument | Description | +| -------- | ----------------------------------- | +| `` | ID of the client to show. Required. | + +# `nitro client delete` + +Delete a client by its ID. This removes the client and all of its versions. + +```shell +nitro client delete "" +``` + +## Arguments + +| Argument | Description | +| -------- | ---------------------------------------------------------------------------------------------------------------- | +| `` | ID of the client to delete. Required when running non-interactively. Interactive runs prompt to select a client. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/environment.md b/website/src/docs/nitro/cli/environment.md new file mode 100644 index 00000000000..bf891c47682 --- /dev/null +++ b/website/src/docs/nitro/cli/environment.md @@ -0,0 +1,69 @@ +--- +title: environment +--- + +The `nitro environment` commands manage environments. An environment is a workspace-level grouping that holds a list of variables that can be reused across documents in the Nitro UI. + +All `environment` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro environment create` + +Create a new environment in a workspace. + +```shell +nitro environment create --name "" +``` + +## Options + +| Option | Env | Description | +| ------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- | +| `-n, --name ` | | Display name of the environment (for example `dev`, `staging`, `production`). Required. | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace to create the environment in. Falls back to the workspace from the current session. | + +When run interactively without `--name`, the CLI prompts for it. + +## Examples + +Create an environment in the current workspace: + +```shell +nitro environment create --name "" +``` + +Create an environment in a specific workspace: + +```shell +nitro environment create \ + --name "" \ + --workspace-id "" +``` + +# `nitro environment list` + +List all environments in a workspace. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro environment list +``` + +## Options + +| Option | Env | Description | +| ------------------------------- | -------------------- | -------------------------------------------------------------------------- | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace. Falls back to the workspace from the current session. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro environment show` + +Show the details of an environment by its ID. + +```shell +nitro environment show "" +``` + +## Arguments + +| Argument | Description | +| -------- | ---------------------------------------- | +| `` | ID of the environment to show. Required. | diff --git a/website/src/docs/nitro/cli/fusion.md b/website/src/docs/nitro/cli/fusion.md new file mode 100644 index 00000000000..6060d2609f7 --- /dev/null +++ b/website/src/docs/nitro/cli/fusion.md @@ -0,0 +1,360 @@ +--- +title: fusion +--- + +The `nitro fusion` commands manage [Fusion](/docs/fusion) configurations. A Fusion configuration is the composed gateway artifact built from one or more source schemas. Once published to a stage, the gateway loads it and starts serving the federated graph. + +# `nitro fusion upload` + +Upload a source schema for a later composition. The schema is stored on the Nitro backend under the given API and tag and can be referenced by name from a subsequent `nitro fusion publish` call (via `--source-schema`). + +```shell +nitro fusion upload \ + --api-id "" \ + --tag "" \ + --source-schema-file "" +``` + +## Options + +| Option | Env | Description | +| ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the schema version being uploaded (for example a Git commit SHA or release tag). Required. | +| `-f, --source-schema-file ` | | Path to a source schema file (`.graphqls`) or to a directory that contains one. Required. | +| `-w, --working-directory ` | | Working directory for the command. Used for relative paths. | + +> `--source-schema-file` accepts either a schema file or a directory. In both cases, a `schema-settings.json` file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory). + +## Examples + +Upload a single source schema: + +```shell +nitro fusion upload \ + --api-id "" \ + --tag "v1" \ + --source-schema-file ./products/schema.graphqls +``` + +# `nitro fusion publish` + +Publish a Fusion configuration to a stage. + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "" \ + --tag "" \ + --source-schema products +``` + +## Options + +| Option | Env | Description | +| ----------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the schema version to deploy (for example a Git commit SHA or release tag). Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to publish to. Required. | +| `-s, --source-schema ` | | One or more source schemas to include in the composition. Each value is either a name (`example`) or a name plus version (`example@1.0.0`). When the version is omitted, the value of `--tag` is used. | +| `-f, --source-schema-file ` | | One or more paths to a source schema file (`.graphqls`) or to a directory that contains one. | +| `-a, --archive ` | `NITRO_FUSION_CONFIG_FILE` | Path to a Fusion archive file. The `--configuration` alias is deprecated. | +| `--legacy-v1-archive ` | | Path to a Fusion v1 archive file. Only intended for use during the migration from Fusion v1 to Fusion v2+. | +| `--force` | | Skip confirmation prompts for deletes and overwrites. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Block the command until a reviewer approves the deployment. Required when the stage gates deployments. | +| `-w, --working-directory ` | | Working directory for the command. Used for resolving relative paths and auto-discovering source schema files. | + +> `--source-schema-file` accepts either a schema file or a directory. In both cases, a `schema-settings.json` file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory). + +## Examples + +Compose and publish from previously uploaded source schemas: + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "dev" \ + --tag "v1" \ + --source-schema products \ + --source-schema reviews +``` + +Compose and publish from local source schema files in one step: + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "dev" \ + --tag "v1" \ + --source-schema-file ./products/schema.graphqls \ + --source-schema-file ./reviews/schema.graphqls +``` + +Publish a pre-composed archive: + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "dev" \ + --tag "v1" \ + --archive ./gateway.far +``` + +# Advanced: multi-step publish + +> Reach for these commands only when `nitro fusion publish` cannot model your pipeline, for example when validation must run in one CI job and the deploy must run in a separate, manually approved job. For everything else, prefer `nitro fusion publish`. The subcommands below split the same flow into individual steps, which is more error-prone and harder to monitor. + +A multi-step publish is driven by a single request ID. `begin` allocates a deployment slot and prints a request ID, every following step references that ID (either explicitly via `--request-id` or implicitly via local state that the CLI caches between commands in the same job). The standard order is `begin` → `start` → `validate` → `commit`. `cancel` releases the slot at any time before `commit`. + +## `nitro fusion publish begin` + +Begin a Fusion configuration publish by requesting a deployment slot for a stage. The returned request ID identifies the publish for every subsequent step. + +```shell +nitro fusion publish begin \ + --api-id "" \ + --tag "" \ + --stage "" +``` + +| Option | Env | Description | +| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the schema version to deploy. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to publish to. Required. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Block the command until a reviewer approves the deployment. Required when the stage gates deployments. | + +## `nitro fusion publish start` + +Mark the publish as started. After this step the deployment is in flight and the configuration is being applied to the gateway. + +```shell +nitro fusion publish start --request-id "" +``` + +| Option | Env | Description | +| --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------- | +| `--request-id ` | `NITRO_REQUEST_ID` | Request ID returned by `begin`. Falls back to the cached ID from the previous step in the same shell. | + +## `nitro fusion publish validate` + +Validate a composed Fusion archive against everything currently published to the stage targeted by the request. + +```shell +nitro fusion publish validate \ + --request-id "" \ + --archive "" +``` + +| Option | Env | Description | +| --------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- | +| `--request-id ` | `NITRO_REQUEST_ID` | Request ID returned by `begin`. Falls back to the cached ID from the previous step in the same shell. | +| `-a, --archive ` | `NITRO_FUSION_CONFIG_FILE` | Path to the Fusion archive to validate. Required. The `--configuration` alias is deprecated. | + +## `nitro fusion publish commit` + +Commit the Fusion configuration, finalizing the publish. After this step the new configuration is live on the stage. + +```shell +nitro fusion publish commit \ + --request-id "" \ + --archive "" +``` + +| Option | Env | Description | +| --------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- | +| `--request-id ` | `NITRO_REQUEST_ID` | Request ID returned by `begin`. Falls back to the cached ID from the previous step in the same shell. | +| `-a, --archive ` | `NITRO_FUSION_CONFIG_FILE` | Path to the Fusion archive to commit. Required. The `--configuration` alias is deprecated. | + +## `nitro fusion publish cancel` + +Cancel an in-progress publish and release the deployment slot. Run this from the failure branch of any job between `begin` and `commit`. + +```shell +nitro fusion publish cancel --request-id "" +``` + +| Option | Env | Description | +| --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------- | +| `--request-id ` | `NITRO_REQUEST_ID` | Request ID returned by `begin`. Falls back to the cached ID from the previous step in the same shell. | + +# `nitro fusion validate` + +Validate a Fusion configuration against a stage. Composes the supplied source schemas (or uses a pre-composed archive) and runs the same checks as `publish` without requesting a deployment slot. + +```shell +nitro fusion validate \ + --api-id "" \ + --stage "" \ + --archive "" +``` + +## Options + +| Option | Env | Description | +| ----------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to validate against. Required. | +| `-a, --archive ` | `NITRO_FUSION_CONFIG_FILE` | Path to a pre-composed Fusion archive file. The `--configuration` alias is deprecated. | +| `--legacy-v1-archive ` | | Path to a Fusion v1 archive file. Only intended for use during the migration from Fusion v1 to Fusion v2+. | +| `-f, --source-schema-file ` | | One or more paths to a source schema file (`.graphqls`) or to a directory that contains one. | + +> `--source-schema-file` accepts either a schema file or a directory. In both cases, a `schema-settings.json` file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory). + +## Examples + +Validate by composing source schemas on the fly: + +```shell +nitro fusion validate \ + --api-id "" \ + --stage "dev" \ + --source-schema-file ./products/schema.graphqls \ + --source-schema-file ./reviews/schema.graphqls +``` + +Validate a pre-composed archive: + +```shell +nitro fusion validate \ + --api-id "" \ + --stage "dev" \ + --archive ./gateway.far +``` + +# `nitro fusion download` + +Download the most recent gateway configuration of a stage to a local archive file. + +```shell +nitro fusion download \ + --api-id "" \ + --stage "" \ + --output-file "" +``` + +## Options + +| Option | Env | Description | +| ----------------------------- | ------------------- | ----------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to download from. Required. | +| `--version ` | | Version of the archive format to request. Defaults to the latest archive version. | +| `--output-file ` | `NITRO_OUTPUT_FILE` | File path to write the archive to. When omitted, the archive is streamed to stdout. | + +## Examples + +Download the live `dev` configuration: + +```shell +nitro fusion download \ + --api-id "" \ + --stage "dev" \ + --output-file ./gateway.far +``` + +# `nitro fusion compose` + +Compose multiple source schemas into a single composite schema and write the result to a Fusion archive. + +```shell +nitro fusion compose \ + --source-schema-file "" \ + --archive "" +``` + +## Options + +| Option | Env | Description | +| ----------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-f, --source-schema-file ` | | One or more paths to a source schema file (`.graphqls`) or to a directory that contains one. When omitted, source schemas are auto-discovered from the working directory. | +| `-a, --archive ` | `NITRO_FUSION_CONFIG_FILE` | Path to the output Fusion archive file. The `--configuration` alias is deprecated. | +| `-e, --env, --environment ` | | Name of the environment used for value substitution in `schema-settings.json` files. | +| `--enable-global-object-identification` | | Add the `Query.node` field for global object identification. | +| `--include-satisfiability-paths` | | Include paths in satisfiability error messages to make composition errors easier to diagnose. | +| `--watch` | | Watch source files for changes and recompose automatically. | +| `-w, --working-directory ` | | Working directory for the command. Used for relative paths and source schema auto-discovery. | +| `--exclude-by-tag ` | | One or more tags to exclude from the composition. | + +> `--source-schema-file` accepts either a schema file or a directory. In both cases, a `schema-settings.json` file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory). + +## Examples + +Compose a gateway from two source schemas: + +```shell +nitro fusion compose \ + --source-schema-file ./products/schema.graphqls \ + --source-schema-file ./reviews/schema.graphqls \ + --archive ./gateway.far \ + --env "dev" +``` + +Auto-discover source schemas from a working directory: + +```shell +nitro fusion compose \ + --working-directory ./subgraphs \ + --archive ./gateway.far +``` + +# `nitro fusion settings set` + +Set a Fusion composition setting on a Fusion archive. Use this to flip composition-level toggles after a composition has been produced, without recomposing from sources. + +```shell +nitro fusion settings set \ + --archive "" +``` + +## Arguments + +| Argument | Description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `` | Name of the setting to change. One of `cache-control-merge-behavior`, `exclude-by-tag`, `global-object-identification`, `tag-merge-behavior`. | +| `` | New value for the setting. Required. | + +## Options + +| Option | Env | Description | +| ---------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------- | +| `-a, --archive ` | `NITRO_FUSION_CONFIG_FILE` | Path to the Fusion archive file to update. Required. The `--configuration` alias is deprecated. | +| `-e, --env, --environment ` | | Name of the environment used for value substitution in `schema-settings.json` files. | + +## Examples + +Enable global object identification on an archive: + +```shell +nitro fusion settings set global-object-identification "true" \ + --archive ./gateway.far \ + --env "dev" +``` + +# `nitro fusion run` + +Start a Fusion gateway locally with the specified archive. Useful for smoke-testing a composed archive before publishing. Only supports Fusion v2. + +```shell +nitro fusion run "" +``` + +## Arguments + +| Argument | Description | +| ---------------- | ------------------------------------------------- | +| `` | Path to the Fusion archive file to run. Required. | + +## Options + +| Option | Description | +| ------------------- | ------------------------------------ | +| `-p, --port ` | The port the gateway will listen on. | + +## Examples + +Run a gateway on port 5000: + +```shell +nitro fusion run ./gateway.far --port 5000 +``` diff --git a/website/src/docs/nitro/cli/global-options.md b/website/src/docs/nitro/cli/global-options.md index 7bf03084c87..967d51a31e6 100644 --- a/website/src/docs/nitro/cli/global-options.md +++ b/website/src/docs/nitro/cli/global-options.md @@ -2,22 +2,26 @@ title: Global Options --- -Many commands in the `nitro` CLI share common options. These options are used to configure the CLI's behavior and authentication. Here are the common options: +# `-?, -h, --help` -# `--cloud-url ` - -Specifies the URL where the Nitro server is located. By default, this points to the shared clusters at `api.chillicream.com`. If you have a self-hosted instance or a dedicated instance, you need to change this value to point to your server. - -You can set this option from the environment variable `NITRO_CLOUD_URL`. +Show help and usage information for the command. Use this on any subcommand to see its options, environment variables, and an example invocation. # `--api-key ` -Accepts API keys created via the `nitro api-key create` command or personal access tokens (PATs) created with the `nitro pat create` command. If you are running in the interactive mode in the CLI, you can also use `nitro login` to authenticate. +API key or Personal Access Token used to authenticate non-interactive CLI calls. Pass either an API key created via [`nitro api-key create`](/docs/nitro/cli/api-key) or a PAT created via [`nitro pat create`](/docs/nitro/cli/pat). -You can set this option from the environment variable `NITRO_API_KEY`. +Set via the `NITRO_API_KEY` environment variable. For interactive use, prefer `nitro login` over passing this flag. # `--output ` -By default, the CLI uses rich text output suitable for human reading. If you want to parse the output programmatically (e.g., using `jq`), you can use this option to get the output in JSON format. This is especially useful when using the CLI in automation scripts or CI/CD pipelines. +Switches the CLI's output format. The only supported value is `json`, which renders a structured JSON document instead of the default human-readable output. + +Setting `--output json` also enables non-interactive mode: prompts are disabled and any missing required input results in an error instead of an interactive question. Use this in CI, scripts, and any pipeline that needs to parse CLI output. + +Set via the `NITRO_OUTPUT_FORMAT` environment variable. + +# `--cloud-url ` + +URL of the Nitro backend the CLI talks to. Only needed for self-hosted or dedicated deployments, the public ChilliCream Cloud is the default. -You can set this option from the environment variable `NITRO_OUTPUT_FORMAT`. +Set via the `NITRO_CLOUD_URL` environment variable. Defaults to `api.chillicream.com`. diff --git a/website/src/docs/nitro/cli/index.md b/website/src/docs/nitro/cli/index.md deleted file mode 100644 index 3f1b793b50c..00000000000 --- a/website/src/docs/nitro/cli/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Nitro CLI Documentation - -Nitro CLI is a powerful .NET command-line tool used for managing your GraphQL API's schema and client registries. It provides a suite of commands that facilitate the handling of schemas, clients, stages, workspaces, environments, and API keys. - -# Getting Started - -To install Nitro CLI, use the .NET Core CLI command: - -```shell -dotnet tool install --global ChilliCream.Nitro.CLI -``` diff --git a/website/src/docs/nitro/cli/installation.md b/website/src/docs/nitro/cli/installation.md new file mode 100644 index 00000000000..e9081b61197 --- /dev/null +++ b/website/src/docs/nitro/cli/installation.md @@ -0,0 +1,66 @@ +--- +title: Installation +--- + + + +The Nitro CLI ships in several flavors so you can pick whatever fits your environment best. + +# .NET tool + +If you have the .NET SDK installed, you can install the CLI as a [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools). + +Install as a local tool, scoped to a repository via a tool manifest. From the repository root: + +```shell +dotnet new tool-manifest +dotnet tool install ChilliCream.Nitro.CommandLine +``` + +Local tools are restored with `dotnet tool restore` and invoked through `dotnet tool run nitro` (or `dotnet nitro`). Check the manifest (`./.config/dotnet-tools.json`) into source control so every collaborator uses the same version. + +Or install globally: + +```shell +dotnet tool install -g ChilliCream.Nitro.CommandLine +``` + +# npm + +The CLI is published to npm as [`@chillicream/nitro`](https://www.npmjs.com/package/@chillicream/nitro). For one-off invocations run it with `npx`. The `@latest` tag opts out of npm's local cache so each run pulls the newest release: + +```shell +npx @chillicream/nitro@latest --version +``` + +# Homebrew (macOS and Linux) + +The CLI is available through the [`chillicream/tools`](https://github.com/ChilliCream/homebrew-tools) tap: + +```shell +brew tap chillicream/tools +brew install nitro-cli +``` + +To upgrade later: + +```shell +brew update +brew upgrade nitro-cli +``` + +# Pre-built binaries + +Pre-built binaries for every supported OS and architecture are attached to each [GitHub release](https://github.com/ChilliCream/graphql-platform/releases). + +| Platform | Asset | +| --------------------------- | ----------------------------- | +| Linux x64 | `nitro-linux-x64.tar.gz` | +| Linux x64 (musl, Alpine) | `nitro-linux-musl-x64.tar.gz` | +| Linux arm64 | `nitro-linux-arm64.tar.gz` | +| macOS x64 (Intel) | `nitro-osx-x64.zip` | +| macOS arm64 (Apple Silicon) | `nitro-osx-arm64.zip` | +| Windows x64 | `nitro-win-x64.zip` | +| Windows x86 | `nitro-win-x86.zip` | + +Extract the archive and place the `nitro` binary somewhere on your `PATH`. The binaries are self-contained, no .NET SDK or runtime is required on the target machine. diff --git a/website/src/docs/nitro/cli/mcp.md b/website/src/docs/nitro/cli/mcp.md new file mode 100644 index 00000000000..ee70657deec --- /dev/null +++ b/website/src/docs/nitro/cli/mcp.md @@ -0,0 +1,185 @@ +--- +title: mcp +--- + +The `nitro mcp` commands manage MCP feature collections. An MCP feature collection bundles a versioned set of prompt and tool definitions that HotChocolate (Fusion) serves to MCP clients on a given stage. + +A typical workflow is: `create` a collection on an API, `upload` a new version of its prompts and tools, optionally `validate` that version against a stage, then `publish` it. + +> Validation runs automatically as part of `nitro mcp publish`. Use `nitro mcp validate` only when you need to gate a deploy step in a separate pipeline job. + +All `mcp` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro mcp create` + +Create a new MCP feature collection on an API. + +```shell +nitro mcp create \ + --name "" \ + --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `--name ` | `NITRO_MCP_FEATURE_COLLECTION_NAME` | Display name of the MCP feature collection. Required. | +| `--api-id ` | `NITRO_API_ID` | ID of the API the collection belongs to. Required when no workspace is set in the session. Get the ID from `nitro api list` or the Nitro UI. | + +## Examples + +Create a collection interactively (prompts for missing values): + +```shell +nitro mcp create +``` + +Create a collection non-interactively: + +```shell +nitro mcp create --name "" --api-id "" +``` + +# `nitro mcp upload` + +Upload a new version of an MCP feature collection. Prompt and tool definition files are picked up via glob patterns. + +```shell +nitro mcp upload \ + --mcp-feature-collection-id "" \ + --tag "" \ + --prompt-pattern "" \ + --tool-pattern "" +``` + +## Options + +| Option | Env | Description | +| --------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------ | +| `--mcp-feature-collection-id ` | `NITRO_MCP_FEATURE_COLLECTION_ID` | ID of the MCP feature collection. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the version being uploaded (for example a Git commit SHA or release tag). Required. | +| `-p, --prompt-pattern ` | | One or more glob patterns for locating MCP prompt definition files (`*.json`). | +| `-t, --tool-pattern ` | | One or more glob patterns for locating MCP tool definition files (`*.graphql`). | + +## Examples + +Upload prompts and tools from the default folders: + +```shell +nitro mcp upload \ + --mcp-feature-collection-id "" \ + --tag "v1" \ + --prompt-pattern "./prompts/**/*.json" \ + --tool-pattern "./tools/**/*.graphql" +``` + +# `nitro mcp publish` + +Publish a previously uploaded MCP feature collection version to a stage. The version is identified by its tag. + +```shell +nitro mcp publish \ + --mcp-feature-collection-id "" \ + --tag "" \ + --stage "" +``` + +## Options + +| Option | Env | Description | +| --------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `--mcp-feature-collection-id ` | `NITRO_MCP_FEATURE_COLLECTION_ID` | ID of the MCP feature collection. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the version to publish. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to publish to. Required. | +| `--force` | | Skip confirmation prompts for deletes and overwrites. Mutually exclusive with `--wait-for-approval`. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Block the command until a reviewer approves the deployment. Mutually exclusive with `--force`. Required when the stage gates deployments. | + +## Examples + +Publish to `dev`: + +```shell +nitro mcp publish \ + --mcp-feature-collection-id "" \ + --stage "dev" \ + --tag "v1" +``` + +Publish to a gated stage and wait for approval: + +```shell +nitro mcp publish \ + --mcp-feature-collection-id "" \ + --stage "production" \ + --tag "v1" \ + --wait-for-approval +``` + +# `nitro mcp validate` + +Validate a new MCP feature collection version against a stage without publishing it. Run this in your pull request validation workflow to catch breaking changes before they are merged. + +```shell +nitro mcp validate \ + --mcp-feature-collection-id "" \ + --stage "" \ + --prompt-pattern "" \ + --tool-pattern "" +``` + +## Options + +| Option | Env | Description | +| --------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------- | +| `--mcp-feature-collection-id ` | `NITRO_MCP_FEATURE_COLLECTION_ID` | ID of the MCP feature collection. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to validate against. Required. | +| `-p, --prompt-pattern ` | | One or more glob patterns for locating MCP prompt definition files (`*.json`). | +| `-t, --tool-pattern ` | | One or more glob patterns for locating MCP tool definition files (`*.graphql`). | + +## Examples + +Validate against the `dev` stage: + +```shell +nitro mcp validate \ + --mcp-feature-collection-id "" \ + --stage "dev" \ + --prompt-pattern "./prompts/**/*.json" \ + --tool-pattern "./tools/**/*.graphql" +``` + +# `nitro mcp list` + +List all MCP feature collections of an API. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro mcp list --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | -------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Falls back to interactive selection when omitted. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro mcp delete` + +Delete an MCP feature collection by its ID. Once deleted, the collection and all its versions are no longer accessible to MCP clients. + +```shell +nitro mcp delete "" +``` + +## Arguments + +| Argument | Description | +| -------- | ----------------------------------------------------- | +| `` | ID of the MCP feature collection to delete. Required. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/openapi.md b/website/src/docs/nitro/cli/openapi.md new file mode 100644 index 00000000000..9b025a1f962 --- /dev/null +++ b/website/src/docs/nitro/cli/openapi.md @@ -0,0 +1,179 @@ +--- +title: openapi +--- + +The `nitro openapi` commands manage OpenAPI collections. An OpenAPI collection bundles a versioned set of HTTP endpoint definitions and/or models that HotChocolate (Fusion) uses to expose HTTP endpoints as a GraphQL schema on a given stage. + +A typical workflow is: `create` a collection on an API, `upload` a new version of its HTTP endpoint definitions and/or models, optionally `validate` that version against a stage, then `publish` it. + +> Validation runs automatically as part of `nitro openapi publish`. Use `nitro openapi validate` only when you need to gate a deploy step in a separate pipeline job. + +All `openapi` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro openapi create` + +Create a new OpenAPI collection on an API. + +```shell +nitro openapi create \ + --name "" \ + --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `--name ` | `NITRO_OPENAPI_COLLECTION_NAME` | Display name of the OpenAPI collection. Required. | +| `--api-id ` | `NITRO_API_ID` | ID of the API the collection belongs to. Required when no workspace is set in the session. Get the ID from `nitro api list` or the Nitro UI. | + +## Examples + +Create a collection interactively (prompts for missing values): + +```shell +nitro openapi create +``` + +Create a collection non-interactively: + +```shell +nitro openapi create --name "" --api-id "" +``` + +# `nitro openapi upload` + +Upload a new version of an OpenAPI collection. + +```shell +nitro openapi upload \ + --openapi-collection-id "" \ + --tag "" \ + --pattern "" +``` + +## Options + +| Option | Env | Description | +| ------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `--openapi-collection-id ` | `NITRO_OPENAPI_COLLECTION_ID` | ID of the OpenAPI collection. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the version being uploaded (for example a Git commit SHA or release tag). Required. | +| `-p, --pattern ` | | One or more glob patterns selecting `*.graphql` files defining HTTP endpoints / models definitions. Required. | + +## Examples + +Upload all OpenAPI documents matching a pattern: + +```shell +nitro openapi upload \ + --openapi-collection-id "" \ + --tag "v1" \ + --pattern "./**/*.graphql" +``` + +# `nitro openapi publish` + +Publish a previously uploaded OpenAPI collection version to a stage. The version is identified by its tag. + +```shell +nitro openapi publish \ + --openapi-collection-id "" \ + --tag "" \ + --stage "" +``` + +## Options + +| Option | Env | Description | +| ------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `--openapi-collection-id ` | `NITRO_OPENAPI_COLLECTION_ID` | ID of the OpenAPI collection. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the version to publish. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to publish to. Required. | +| `--force` | | Skip confirmation prompts for deletes and overwrites. Mutually exclusive with `--wait-for-approval`. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Block the command until a reviewer approves the deployment. Mutually exclusive with `--force`. Required when the stage gates deployments. | + +## Examples + +Publish to `dev`: + +```shell +nitro openapi publish \ + --openapi-collection-id "" \ + --stage "dev" \ + --tag "v1" +``` + +Publish to a gated stage and wait for approval: + +```shell +nitro openapi publish \ + --openapi-collection-id "" \ + --stage "production" \ + --tag "v1" \ + --wait-for-approval +``` + +# `nitro openapi validate` + +Validate a new OpenAPI collection version against a stage without publishing it. Run this in your pull request validation workflow to catch breaking changes before they are merged. + +```shell +nitro openapi validate \ + --openapi-collection-id "" \ + --stage "" \ + --pattern "" +``` + +## Options + +| Option | Env | Description | +| ------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `--openapi-collection-id ` | `NITRO_OPENAPI_COLLECTION_ID` | ID of the OpenAPI collection. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to validate against. Required. | +| `-p, --pattern ` | | One or more glob patterns selecting `*.graphql` files defining HTTP endpoints / models definitions. Required. | + +## Examples + +Validate against the `dev` stage: + +```shell +nitro openapi validate \ + --openapi-collection-id "" \ + --stage "dev" \ + --pattern "./**/*.graphql" +``` + +# `nitro openapi list` + +List all OpenAPI collections of an API. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro openapi list --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | -------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Falls back to interactive selection when omitted. | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro openapi delete` + +Delete an OpenAPI collection by its ID. Once deleted, the collection and all its versions are no longer accessible. + +```shell +nitro openapi delete "" +``` + +## Arguments + +| Argument | Description | +| -------- | ------------------------------------------------- | +| `` | ID of the OpenAPI collection to delete. Required. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/pat.md b/website/src/docs/nitro/cli/pat.md new file mode 100644 index 00000000000..205b09e9f96 --- /dev/null +++ b/website/src/docs/nitro/cli/pat.md @@ -0,0 +1,92 @@ +--- +title: pat +--- + +The `nitro pat` commands manage Personal Access Tokens (PATs). A PAT is bound to your user account and acts on your behalf, so it inherits your access across every workspace and API you are a member of. PATs are intended for personal automation, scripts on your machine, and bootstrapping operations that need broader permissions than an [API key](/docs/nitro/cli/api-key) provides (for example creating workspaces or managing members). + +For narrower, non-user-bound automation (CI/CD, deploy pipelines, telemetry from your GraphQL server), prefer an [API key](/docs/nitro/cli/api-key) scoped to a single API or workspace. + +To use a PAT for non-interactive CLI calls, pass it via `--api-key` (or `NITRO_API_KEY`). The Nitro server accepts both PATs and API keys through the same option. + +> Treat a PAT like a password. It can do anything you can do, store the secret in a secret manager and revoke it as soon as you no longer need it. + +All `pat` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro pat create` + +Create a new personal access token. The secret is returned only once at creation time, store it in a secure location (for example a secret manager) before closing the terminal. + +```shell +nitro pat create \ + --description "" \ + --expires "" +``` + +## Options + +| Option | Env | Description | +| ----------------------------- | ------------------- | ---------------------------------------------------------------------- | +| `--description ` | `NITRO_DESCRIPTION` | Human-readable description used to identify the token later. Required. | +| `--expires ` | `NITRO_EXPIRES` | Expiration time of the token in days. Default: `180`. | + +## Examples + +Create a token with the default 180-day expiration: + +```shell +nitro pat create --description "" +``` + +Create a short-lived token: + +```shell +nitro pat create --description "" --expires "30" +``` + +Capture the secret in a script: + +```shell +SECRET=$(nitro pat create \ + --description "" \ + --output json | jq -r '.secret') +``` + +Use the captured secret to authenticate subsequent CLI calls: + +```shell +nitro workspace list --api-key "$SECRET" +``` + +# `nitro pat list` + +List the personal access tokens on your user account. Results are paginated, use the returned cursor to fetch the next page. Secrets are not returned, only metadata. + +```shell +nitro pat list +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | -------------------------------------------------------------------- | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro pat revoke` + +Revoke a personal access token by its ID. Once revoked, any client using the token loses access immediately. + +```shell +nitro pat revoke "" +``` + +## Arguments + +| Argument | Description | +| -------- | ---------------------------------------------------- | +| `` | ID of the personal access token to revoke. Required. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/schema.md b/website/src/docs/nitro/cli/schema.md new file mode 100644 index 00000000000..0809c4d0f90 --- /dev/null +++ b/website/src/docs/nitro/cli/schema.md @@ -0,0 +1,143 @@ +--- +title: schema +--- + +The `nitro schema` commands manage the GraphQL schema (SDL) of an API. + +The typical flow is: `upload` a new version, `validate` it against the target stage to detect breaking changes, then `publish` it once the changes are safe. `download` retrieves the schema currently published to a stage, which is useful for code generation and local tooling. + +> For HotChocolate Fusion gateways, use the [`nitro fusion`](/docs/nitro/cli/fusion) commands instead. + +All `schema` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro schema upload` + +Upload a new schema version to an API. The version is identified by a tag and is not yet published to any stage. + +```shell +nitro schema upload \ + --api-id "" \ + --tag "" \ + --schema-file +``` + +## Options + +| Option | Env | Description | +| ----------------------------- | ------------------- | -------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API to upload to. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the new schema version, for example `v1` or a Git commit. Required. | +| `--schema-file ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the schema definition. Required. | + +## Examples + +Upload a schema version: + +```shell +nitro schema upload \ + --api-id "" \ + --tag "v1" \ + --schema-file ./schema.graphqls +``` + +# `nitro schema publish` + +Publish a previously uploaded schema version to a stage. The version is identified by its tag. + +```shell +nitro schema publish \ + --api-id "" \ + --tag "" \ + --stage "" +``` + +## Options + +| Option | Env | Description | +| --------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--tag ` | `NITRO_TAG` | Tag of the schema version to publish. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to publish to. Required. | +| `--force` | | Skip confirmation prompts and publish even when the version contains breaking changes. Mutually exclusive with `--wait-for-approval`. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Block the command until a reviewer approves the deployment. Mutually exclusive with `--force`. Required when the stage gates deployments. | + +## Examples + +Publish to `dev`: + +```shell +nitro schema publish \ + --api-id "" \ + --tag "v1" \ + --stage "dev" +``` + +Publish to a gated stage and wait for approval: + +```shell +nitro schema publish \ + --api-id "" \ + --tag "v1" \ + --stage "production" \ + --wait-for-approval +``` + +# `nitro schema validate` + +Validate a new schema version against a stage without publishing it. Run this in your pull request validation workflow to catch breaking changes before they are merged. + +```shell +nitro schema validate \ + --api-id "" \ + --stage "" \ + --schema-file +``` + +## Options + +| Option | Env | Description | +| ----------------------------- | ------------------- | -------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to validate against. Required. | +| `--schema-file ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the schema definition. Required. | + +## Examples + +Validate against the `dev` stage: + +```shell +nitro schema validate \ + --api-id "" \ + --stage "dev" \ + --schema-file ./schema.graphqls +``` + +# `nitro schema download` + +Download the schema currently published to a stage and write it to a file. + +```shell +nitro schema download \ + --api-id "" \ + --stage "" \ + --output-file +``` + +## Options + +| Option | Env | Description | +| ----------------------------- | ------------------- | ------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to download from. Required. | +| `--output-file ` | `NITRO_OUTPUT_FILE` | Path to write the schema to. If the file exists, it is overwritten. | + +## Examples + +Download the `dev` schema to a local file: + +```shell +nitro schema download \ + --api-id "" \ + --stage "dev" \ + --output-file ./schema.graphqls +``` diff --git a/website/src/docs/nitro/cli/session.md b/website/src/docs/nitro/cli/session.md new file mode 100644 index 00000000000..22c2265c9c2 --- /dev/null +++ b/website/src/docs/nitro/cli/session.md @@ -0,0 +1,61 @@ +--- +title: session +--- + +The session commands manage your CLI authentication and provide quick access to the Nitro web UI. Use `nitro login` to authenticate interactively, `nitro logout` to clear the local session, `nitro status` to inspect who you're logged in as, and `nitro launch` to open Nitro in your default browser. + +For non-interactive environments such as CI/CD, skip `nitro login` entirely and authenticate per-invocation with `--api-key` instead (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro login` + +The `nitro login` command logs you in interactively through your default browser. After authenticating, the CLI prompts you to select a default workspace (skipped when you only have one) and persists the session locally so subsequent commands don't need `--api-key`. + +```shell +nitro login +``` + +## Arguments + +| Argument | Description | +| -------- | ------------------------------------------------------------------------------- | +| `` | URL of the Nitro backend. Only needed for self-hosted or dedicated deployments. | + +## Examples + +Log in against the default Nitro Cloud: + +```shell +nitro login +``` + +Log in against a self-hosted or dedicated deployment using the positional argument: + +```shell +nitro login "" +``` + +# `nitro logout` + +The `nitro logout` command logs you out and removes the locally stored session information. After logout, subsequent commands either need a fresh `nitro login` or an explicit `--api-key`. + +```shell +nitro logout +``` + +# `nitro status` + +The `nitro status` command displays the current session status, including the logged-in user, the active workspace (if one is selected), and the backend URL when it differs from the default. + +The `status` command requires authentication. Run `nitro login` first or pass `--api-key`. + +```shell +nitro status +``` + +# `nitro launch` + +The `nitro launch` command opens the Nitro web UI in your default browser. + +```shell +nitro launch +``` diff --git a/website/src/docs/nitro/cli/stage.md b/website/src/docs/nitro/cli/stage.md new file mode 100644 index 00000000000..089ef8af0aa --- /dev/null +++ b/website/src/docs/nitro/cli/stage.md @@ -0,0 +1,82 @@ +--- +title: stage +--- + +The `nitro stage` commands manage the stages of an API. Stages represent deployment targets (for example dev, staging, production) that artifacts like schemas, clients, and fusion configurations are published to. + +Stages are not created with a dedicated `create` command. Instead, the full set of stages for an API is declared together with `nitro stage edit`, either interactively or by passing a JSON `--configuration`. Conditions on a stage (such as `afterStage`) do not have any effect besides how the UI for the stages is being rendered. + +All `stage` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro stage edit` + +Edit the stages of an API. When `--configuration` is omitted, an interactive editor lets you add, rename, reorder, and delete stages. In non-interactive mode the configuration must be supplied as JSON. + +```shell +nitro stage edit \ + --configuration "[{\"name\":\"dev\",\"displayName\":\"Dev\",\"conditions\":[]}]" \ + --api-id "" +``` + +## Options + +| Option | Env | Description | +| --------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API whose stages you are editing. Required. | +| `--configuration ` | | Stage configuration as a JSON array. Each entry has `name`, `displayName`, and a `conditions` array (for example `[{"afterStage":"dev"}]`). If omitted, the CLI opens an interactive editor. | + +## Examples + +Open the interactive editor for an API: + +```shell +nitro stage edit --api-id "" +``` + +Replace the stages of an API with a single `dev` stage: + +```shell +nitro stage edit \ + --api-id "" \ + --configuration "[{\"name\":\"dev\",\"displayName\":\"Dev\",\"conditions\":[]}]" +``` + +Define a `dev` to `prod` promotion chain: + +```shell +nitro stage edit \ + --api-id "" \ + --configuration "[{\"name\":\"dev\",\"displayName\":\"Dev\",\"conditions\":[]},{\"name\":\"prod\",\"displayName\":\"Production\",\"conditions\":[{\"afterStage\":\"dev\"}]}]" +``` + +# `nitro stage list` + +List all stages of an API, including their conditions. + +```shell +nitro stage list --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | ------------------------ | +| `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | + +# `nitro stage delete` + +Delete a single stage by name. Removing a stage that other parts of your workflow depend on may fail, resolve those dependencies first. + +```shell +nitro stage delete \ + --stage "" \ + --api-id "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API the stage belongs to. Required. | +| `--stage ` | `NITRO_STAGE` | Name of the stage to delete. Required. | +| `--force` | | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | diff --git a/website/src/docs/nitro/cli/workspace.md b/website/src/docs/nitro/cli/workspace.md new file mode 100644 index 00000000000..27dc02b086b --- /dev/null +++ b/website/src/docs/nitro/cli/workspace.md @@ -0,0 +1,76 @@ +--- +title: workspace +--- + +The `nitro workspace` commands manage workspaces. A workspace is the top-level container in Nitro, every API, environment, and API key belongs to exactly one workspace. + +The CLI tracks a default workspace per session so most other commands can omit `--workspace-id`. Use `nitro workspace set-default` to change it and `nitro workspace current` to see what is selected. + +All `workspace` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro workspace create` + +Create a new workspace. + +```shell +nitro workspace create --name "" +``` + +## Options + +| Option | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------- | +| `--name ` | Display name of the workspace. Required. | +| `--default` | Set the created workspace as the default for the current session. Pass `--default false` to opt out explicitly. | + +When run interactively without `--name`, the CLI prompts for it. + +# `nitro workspace list` + +List the workspaces you have access to. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro workspace list +``` + +## Options + +| Option | Env | Description | +| ------------------- | -------------- | -------------------------------------------------------------------- | +| `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | + +# `nitro workspace show` + +Show the details of a workspace by its ID. + +```shell +nitro workspace show "" +``` + +## Arguments + +| Argument | Description | +| -------- | -------------------------------------- | +| `` | ID of the workspace to show. Required. | + +# `nitro workspace current` + +Show the name of the currently selected workspace. + +```shell +nitro workspace current +``` + +# `nitro workspace set-default` + +Set the default workspace for the current session. In interactive mode the CLI shows a picker, in non-interactive mode pass `--workspace-id`. + +```shell +nitro workspace set-default +``` + +## Options + +| Option | Env | Description | +| ------------------------------- | -------------------- | ---------------------------------------------------------------------------- | +| `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace to set as the default. Required in non-interactive mode. |