From 0f4f76eed323a8caa50efe6fb75036d92191b1d3 Mon Sep 17 00:00:00 2001 From: tobias-tengler <45513122+tobias-tengler@users.noreply.github.com> Date: Mon, 4 May 2026 15:07:49 +0200 Subject: [PATCH 1/5] Overhault Nitro CLI docs --- website/src/docs/docs.json | 603 ++++++++++++++---- .../src/docs/nitro/cli-commands/api-key.md | 68 -- website/src/docs/nitro/cli-commands/api.md | 88 --- website/src/docs/nitro/cli-commands/client.md | 190 ------ .../docs/nitro/cli-commands/environment.md | 42 -- .../cli-commands/fusion-configuration.md | 132 ---- website/src/docs/nitro/cli-commands/launch.md | 11 - website/src/docs/nitro/cli-commands/login.md | 13 - website/src/docs/nitro/cli-commands/logout.md | 13 - website/src/docs/nitro/cli-commands/pat.md | 66 -- website/src/docs/nitro/cli-commands/schema.md | 85 --- website/src/docs/nitro/cli-commands/stage.md | 111 ---- .../src/docs/nitro/cli-commands/workspace.md | 84 --- website/src/docs/nitro/cli/api-key.md | 136 ++++ website/src/docs/nitro/cli/api.md | 195 ++++++ website/src/docs/nitro/cli/authentication.md | 26 - website/src/docs/nitro/cli/automation.md | 30 - website/src/docs/nitro/cli/client.md | 355 +++++++++++ website/src/docs/nitro/cli/environment.md | 100 +++ website/src/docs/nitro/cli/fusion.md | 399 ++++++++++++ website/src/docs/nitro/cli/global-options.md | 23 - website/src/docs/nitro/cli/index.md | 11 - website/src/docs/nitro/cli/installation.md | 5 + website/src/docs/nitro/cli/launch.md | 17 + website/src/docs/nitro/cli/login.md | 43 ++ website/src/docs/nitro/cli/logout.md | 17 + website/src/docs/nitro/cli/mcp.md | 214 +++++++ website/src/docs/nitro/cli/mock.md | 122 ++++ website/src/docs/nitro/cli/openapi.md | 208 ++++++ website/src/docs/nitro/cli/pat.md | 121 ++++ website/src/docs/nitro/cli/schema.md | 162 +++++ website/src/docs/nitro/cli/stage.md | 113 ++++ website/src/docs/nitro/cli/status.md | 21 + website/src/docs/nitro/cli/workspace.md | 139 ++++ 34 files changed, 2855 insertions(+), 1108 deletions(-) delete mode 100644 website/src/docs/nitro/cli-commands/api-key.md delete mode 100644 website/src/docs/nitro/cli-commands/api.md delete mode 100644 website/src/docs/nitro/cli-commands/client.md delete mode 100644 website/src/docs/nitro/cli-commands/environment.md delete mode 100644 website/src/docs/nitro/cli-commands/fusion-configuration.md delete mode 100644 website/src/docs/nitro/cli-commands/launch.md delete mode 100644 website/src/docs/nitro/cli-commands/login.md delete mode 100644 website/src/docs/nitro/cli-commands/logout.md delete mode 100644 website/src/docs/nitro/cli-commands/pat.md delete mode 100644 website/src/docs/nitro/cli-commands/schema.md delete mode 100644 website/src/docs/nitro/cli-commands/stage.md delete mode 100644 website/src/docs/nitro/cli-commands/workspace.md create mode 100644 website/src/docs/nitro/cli/api-key.md create mode 100644 website/src/docs/nitro/cli/api.md delete mode 100644 website/src/docs/nitro/cli/authentication.md delete mode 100644 website/src/docs/nitro/cli/automation.md create mode 100644 website/src/docs/nitro/cli/client.md create mode 100644 website/src/docs/nitro/cli/environment.md create mode 100644 website/src/docs/nitro/cli/fusion.md delete mode 100644 website/src/docs/nitro/cli/global-options.md delete mode 100644 website/src/docs/nitro/cli/index.md create mode 100644 website/src/docs/nitro/cli/installation.md create mode 100644 website/src/docs/nitro/cli/launch.md create mode 100644 website/src/docs/nitro/cli/login.md create mode 100644 website/src/docs/nitro/cli/logout.md create mode 100644 website/src/docs/nitro/cli/mcp.md create mode 100644 website/src/docs/nitro/cli/mock.md create mode 100644 website/src/docs/nitro/cli/openapi.md create mode 100644 website/src/docs/nitro/cli/pat.md create mode 100644 website/src/docs/nitro/cli/schema.md create mode 100644 website/src/docs/nitro/cli/stage.md create mode 100644 website/src/docs/nitro/cli/status.md create mode 100644 website/src/docs/nitro/cli/workspace.md diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index 961edcbef57..3cfe8dc19a2 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,20 +143,72 @@ "title": "CLI", "items": [ { - "path": "index", - "title": "Introduction" + "path": "installation", + "title": "Installation" }, { - "path": "authentication", - "title": "Authentication" + "path": "login", + "title": "login" + }, + { + "path": "logout", + "title": "logout" + }, + { + "path": "status", + "title": "status" + }, + { + "path": "launch", + "title": "launch" + }, + { + "path": "api", + "title": "api" + }, + { + "path": "api-key", + "title": "api-key" + }, + { + "path": "pat", + "title": "pat" + }, + { + "path": "schema", + "title": "schema" + }, + { + "path": "client", + "title": "client" }, { - "path": "global-options", - "title": "Global Options" + "path": "fusion", + "title": "fusion" }, { - "path": "automation", - "title": "Automation" + "path": "mcp", + "title": "mcp" + }, + { + "path": "openapi", + "title": "openapi" + }, + { + "path": "mock", + "title": "mock" + }, + { + "path": "environment", + "title": "environment" + }, + { + "path": "stage", + "title": "stage" + }, + { + "path": "workspace", + "title": "workspace" } ] }, @@ -119,21 +216,54 @@ "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": "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": "fusion-configuration", "title": "fusion-configuration" }, - { "path": "workspace", "title": "workspace" } + { + "path": "workspace", + "title": "workspace" + } ] }, { @@ -144,17 +274,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 +502,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 +514,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 +792,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 +3282,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 +3308,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..eb713ed77dc --- /dev/null +++ b/website/src/docs/nitro/cli/api-key.md @@ -0,0 +1,136 @@ +--- +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 (Preview). This lets you issue, for example, a `production`-only key that cannot publish to `dev`. + +> 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 (uses the workspace from your session): + +```shell +nitro api-key create --name "" +``` + +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. | + +## Examples + +List keys in the current workspace: + +```shell +nitro api-key list +``` + +Page through all keys in JSON mode: + +```shell +nitro api-key list --output json +nitro api-key list --output json --cursor "" +``` + +# `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`. | + +## Examples + +Delete with confirmation: + +```shell +nitro api-key delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro api-key delete "" --force +``` diff --git a/website/src/docs/nitro/cli/api.md b/website/src/docs/nitro/cli/api.md new file mode 100644 index 00000000000..d3c63c2e98d --- /dev/null +++ b/website/src/docs/nitro/cli/api.md @@ -0,0 +1,195 @@ +--- +title: api +--- + +The `nitro api` commands manage APIs in a workspace. An API represents a single GraphQL endpoint that you publish schemas and clients to. APIs live under a workspace and are addressed by a path (for example `/products/catalog`). + +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. | + +## Examples + +List APIs in the current workspace: + +```shell +nitro api list +``` + +List APIs in an explicit workspace: + +```shell +nitro api list --workspace-id "" +``` + +Page through all APIs in JSON mode: + +```shell +nitro api list --output json +nitro api list --output json --cursor "" +``` + +# `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. | + +## Examples + +Show an API: + +```shell +nitro api show "" +``` + +Capture the API details in a script: + +```shell +nitro api show "" --output json +``` + +# `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`. | + +## Examples + +Delete with confirmation: + +```shell +nitro api delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro api delete "" --force +``` 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..4d7a5ff494e --- /dev/null +++ b/website/src/docs/nitro/cli/client.md @@ -0,0 +1,355 @@ +--- +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. Registering a client lets Nitro detect when a schema change would break an operation that real consumers depend on. + +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, and `validate` runs the same breaking-change detection that `publish` does without committing the result. + +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 \ + --api-id "" \ + --name "" +``` + +## Options + +| Option | Env | Description | +| ------------------- | ------------------- | -------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API to attach the client to. | +| `--name ` | `NITRO_CLIENT_NAME` | Display name of the client. | + +When run interactively, the CLI prompts for any option you omit. Both options are required when running non-interactively. + +## Examples + +Create a client non-interactively: + +```shell +nitro client create \ + --api-id "" \ + --name "" +``` + +# `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. | + +## Examples + +List clients for an API: + +```shell +nitro client list --api-id "" +``` + +Page through all clients in JSON mode: + +```shell +nitro client list --api-id "" --output json +nitro client list --api-id "" --output json --cursor "" +``` + +# `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. | + +## Examples + +List all versions of a client: + +```shell +nitro client list versions --client-id "" +``` + +# `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. | + +## Examples + +List published versions of a client: + +```shell +nitro client list published-versions --client-id "" +``` + +# `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. | + +## Examples + +Show a client: + +```shell +nitro client show "" +``` + +# `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 tagged with a Git commit: + +```shell +nitro client upload \ + --client-id "" \ + --tag "$(git rev-parse HEAD)" \ + --operations-file ./operations.json +``` + +# `nitro client validate` + +Validate a client's operations against a stage without publishing. Returns the operations that would break against the schema currently published to the stage. + +```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 a client against the `dev` stage in a pull request check: + +```shell +nitro client validate \ + --client-id "" \ + --stage "dev" \ + --operations-file ./operations.json +``` + +# `nitro client publish` + +Publish a previously uploaded client version to a stage. By default the publish fails if the version contains operations that break against the stage's schema. Use `--force` to override, or `--wait-for-approval` to pause until a reviewer approves the change in the Nitro UI. + +```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 deploy. 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. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Wait for a reviewer to approve the deployment in Nitro before completing. | + +`--force` and `--wait-for-approval` are mutually exclusive. + +## Examples + +Publish a client version to `dev`: + +```shell +nitro client publish \ + --client-id "" \ + --tag "" \ + --stage "dev" +``` + +Publish to `production` and wait for manual approval: + +```shell +nitro client publish \ + --client-id "" \ + --tag "" \ + --stage "production" \ + --wait-for-approval +``` + +# `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. | + +## 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 the persisted operations of the client version 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 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`. | + +## Examples + +Delete with confirmation: + +```shell +nitro client delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro client delete "" --force +``` diff --git a/website/src/docs/nitro/cli/environment.md b/website/src/docs/nitro/cli/environment.md new file mode 100644 index 00000000000..57bfb7059c2 --- /dev/null +++ b/website/src/docs/nitro/cli/environment.md @@ -0,0 +1,100 @@ +--- +title: environment +--- + +The `nitro environment` commands manage environments. An environment is a workspace-level grouping that holds named [stages](/docs/nitro/cli/stage) (for example `dev`, `staging`, `production`) and is shared across the APIs in the workspace. + +Environments let you align stage names across APIs so promotions, telemetry, and access policies use a consistent vocabulary. Stages themselves are configured per API via `nitro stage edit`. + +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. | + +## Examples + +List environments in the current workspace: + +```shell +nitro environment list +``` + +Page through environments in JSON mode: + +```shell +nitro environment list --output json +nitro environment list --output json --cursor "" +``` + +# `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. | + +## Examples + +Show an environment: + +```shell +nitro environment show "" +``` + +Get the workspace name for an environment in a script: + +```shell +WORKSPACE=$(nitro environment show "" --output json | jq -r '.workspace.name') +``` diff --git a/website/src/docs/nitro/cli/fusion.md b/website/src/docs/nitro/cli/fusion.md new file mode 100644 index 00000000000..a5eca6f3a5c --- /dev/null +++ b/website/src/docs/nitro/cli/fusion.md @@ -0,0 +1,399 @@ +--- +title: fusion +--- + +The `nitro fusion` commands manage [Fusion](/docs/fusion), ChilliCream's federated GraphQL gateway. A Fusion configuration is the composed gateway artifact (a `.far` archive) built from one or more source schemas. Once published to a stage, the gateway loads it and starts serving the federated graph. + +The most common workflow is `compose` locally, then `publish` to a stage. `nitro fusion publish` runs the full publishing flow (validate, start, commit) in a single command and is the right choice for almost every pipeline. + +> Local commands like `compose`, `migrate`, `run`, and `settings set` operate on archive files on disk and do not require authentication. Every other `fusion` command requires authentication, run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro fusion publish` + +Publish a Fusion configuration to a stage. This is the one-shot command that runs validation, requests a deployment slot, and commits the new configuration in sequence. + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "" \ + --tag "" \ + --archive "" +``` + +## 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. | + +## Examples + +Publish a pre-composed archive: + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "dev" \ + --tag "v1" \ + --archive ./gateway.far +``` + +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 +``` + +Compose and publish from previously uploaded source schemas: + +```shell +nitro fusion publish \ + --api-id "" \ + --stage "dev" \ + --tag "v1" \ + --source-schema products \ + --source-schema reviews +``` + +# 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 shell). The standard order is `begin` → `validate` → `start` → `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 validate` + +Validate a composed Fusion archive against the schema and clients on 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 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 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 compose` + +Compose multiple source schemas into a single composite schema and write the result to a Fusion archive. This is the local equivalent of the composition step that `publish` performs, and is useful for inspecting the composed schema or staging an archive before publishing. + +```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. | + +## 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 +``` + +Recompose on file changes during local development: + +```shell +nitro fusion compose \ + --source-schema-file ./products/schema.graphqls \ + --archive ./gateway.far \ + --watch +``` + +# `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 `2.0.0`. | +| `--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 migrate` + +Migrate Fusion configuration files from a legacy format to the current format. Use this once when upgrading an existing Fusion v1 setup. + +```shell +nitro fusion migrate +``` + +## Arguments + +| Argument | Description | +| ------------------- | -------------------------------------------------------------------------- | +| `` | Migration target. Currently the only supported value is `subgraph-config`. | + +## Options + +| Option | Description | +| --------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| `-w, --working-directory ` | Working directory the command searches for files to migrate. Defaults to the current directory. | + +## Examples + +Migrate `subgraph-config.json` files in the current directory: + +```shell +nitro fusion migrate subgraph-config +``` + +Migrate files in a specific directory: + +```shell +nitro fusion migrate subgraph-config --working-directory ./gateway +``` + +# `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 ` | Port the gateway will listen on. When omitted, the default port is used. | + +## Examples + +Run a gateway on port 5000: + +```shell +nitro fusion run ./gateway.far --port 5000 +``` + +# `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. | + +## Examples + +Upload a single source schema: + +```shell +nitro fusion upload \ + --api-id "" \ + --tag "v1" \ + --source-schema-file ./products/schema.graphqls +``` + +# `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. | + +## Examples + +Validate a pre-composed archive: + +```shell +nitro fusion validate \ + --api-id "" \ + --stage "dev" \ + --archive ./gateway.far +``` + +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 +``` + +# `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" +``` diff --git a/website/src/docs/nitro/cli/global-options.md b/website/src/docs/nitro/cli/global-options.md deleted file mode 100644 index 7bf03084c87..00000000000 --- a/website/src/docs/nitro/cli/global-options.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -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: - -# `--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`. - -# `--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. - -You can set this option from the environment variable `NITRO_API_KEY`. - -# `--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. - -You can set this option from the environment variable `NITRO_OUTPUT_FORMAT`. 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..baf91f3e029 --- /dev/null +++ b/website/src/docs/nitro/cli/installation.md @@ -0,0 +1,5 @@ +--- +title: Installation +--- + +TODO diff --git a/website/src/docs/nitro/cli/launch.md b/website/src/docs/nitro/cli/launch.md new file mode 100644 index 00000000000..c5513e200ca --- /dev/null +++ b/website/src/docs/nitro/cli/launch.md @@ -0,0 +1,17 @@ +--- +title: launch +--- + +The `nitro launch` command opens the Nitro web UI in your default browser. It's a convenience shortcut, useful for jumping from the terminal into the UI to create a workspace, browse APIs, or inspect telemetry. + +```shell +nitro launch +``` + +## Examples + +Open the Nitro web UI: + +```shell +nitro launch +``` diff --git a/website/src/docs/nitro/cli/login.md b/website/src/docs/nitro/cli/login.md new file mode 100644 index 00000000000..dd0486c1f42 --- /dev/null +++ b/website/src/docs/nitro/cli/login.md @@ -0,0 +1,43 @@ +--- +title: 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`. + +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)). + +```shell +nitro login +``` + +## Arguments + +| Argument | Description | +| -------- | ------------------------------------------------------------------------------- | +| `` | URL of the Nitro backend. Only needed for self-hosted or dedicated deployments. | + +## Options + +| Option | Env | Description | +| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `--cloud-url ` | `NITRO_CLOUD_URL` | URL of the Nitro backend. Only needed for self-hosted or dedicated deployments. Defaults to `identity.chillicream.com`. | + +## 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 "" +``` + +Log in against a self-hosted or dedicated deployment using the option: + +```shell +nitro login --cloud-url "" +``` diff --git a/website/src/docs/nitro/cli/logout.md b/website/src/docs/nitro/cli/logout.md new file mode 100644 index 00000000000..a5542e0ef41 --- /dev/null +++ b/website/src/docs/nitro/cli/logout.md @@ -0,0 +1,17 @@ +--- +title: 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` (see [Global Options](/docs/nitro/cli/global-options)). + +```shell +nitro logout +``` + +## Examples + +Log out of the current session: + +```shell +nitro logout +``` diff --git a/website/src/docs/nitro/cli/mcp.md b/website/src/docs/nitro/cli/mcp.md new file mode 100644 index 00000000000..b414ad6410d --- /dev/null +++ b/website/src/docs/nitro/cli/mcp.md @@ -0,0 +1,214 @@ +--- +title: mcp +--- + +The `nitro mcp` commands manage MCP feature collections. The Model Context Protocol (MCP) lets AI assistants and other clients discover and invoke capabilities exposed by your API. An MCP feature collection bundles a versioned set of prompt and tool definitions that Nitro 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. | +| `--api-id ` | `NITRO_API_ID` | ID of the API the collection belongs to. 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 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. | + +## Examples + +List collections for an API: + +```shell +nitro mcp list --api-id "" +``` + +Page through collections in JSON mode: + +```shell +nitro mcp list --api-id "" --output json +nitro mcp list --api-id "" --output json --cursor "" +``` + +# `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. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | + +## Examples + +Delete with confirmation: + +```shell +nitro mcp delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro mcp delete "" --force +``` + +# `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 validate` + +Validate a new MCP feature collection version against a stage without publishing it. Use this in CI to catch breaking changes before a deploy job runs. + +```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 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 +``` diff --git a/website/src/docs/nitro/cli/mock.md b/website/src/docs/nitro/cli/mock.md new file mode 100644 index 00000000000..b672a096043 --- /dev/null +++ b/website/src/docs/nitro/cli/mock.md @@ -0,0 +1,122 @@ +--- +title: mock +--- + +The `nitro mock` commands manage mock schemas. A mock schema is a hosted GraphQL endpoint that proxies a downstream service and overlays a schema extension on top of it, useful for prototyping clients against fields that do not yet exist in the real service or for stubbing parts of an API in tests. + +A mock schema is attached to an API and is defined by three pieces: the base `--schema` (the SDL of the downstream service), the `--extension` (additional types and fields layered on top), and the `--url` of the downstream service that real fields are forwarded to. + +All `mock` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `nitro mock create` + +Create a new mock schema under an API. + +```shell +nitro mock create \ + --api-id "" \ + --name "" \ + --schema \ + --extension \ + --url "" +``` + +## Options + +| Option | Env | Description | +| ------------------------- | ----------------------------- | ---------------------------------------------------------------------------------- | +| `--api-id ` | `NITRO_API_ID` | ID of the API to attach the mock schema to. | +| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | Display name of the mock schema. Required. | +| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the base schema. Required. | +| `--extension ` | `NITRO_SCHEMA_EXTENSION_FILE` | Path to the GraphQL file with the schema extension. Required. | +| `--url ` | `NITRO_DOWNSTREAM_URL` | URL of the downstream GraphQL service that real fields are forwarded to. Required. | + +## Examples + +Create a mock schema for a downstream service: + +```shell +nitro mock create \ + --api-id "" \ + --name "" \ + --schema ./schema.graphqls \ + --extension ./extension.graphql \ + --url "https://example.com/graphql" +``` + +# `nitro mock list` + +List all mock schemas in an API. Results are paginated, use the returned cursor to fetch the next page. + +```shell +nitro mock 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. | + +## Examples + +List mock schemas for an API: + +```shell +nitro mock list --api-id "" +``` + +Page through all mock schemas in JSON mode: + +```shell +nitro mock list --api-id "" --output json +nitro mock list --api-id "" --output json --cursor "" +``` + +# `nitro mock update` + +Update an existing mock schema. Every option is optional, only the fields you pass are changed. + +```shell +nitro mock update "" \ + --schema \ + --extension +``` + +## Arguments + +| Argument | Description | +| -------- | ------------------------------------------ | +| `` | ID of the mock schema to update. Required. | + +## Options + +| Option | Env | Description | +| ------------------------- | ----------------------------- | ------------------------------------------------------- | +| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | New display name of the mock schema. | +| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the new base schema. | +| `--extension ` | `NITRO_SCHEMA_EXTENSION_FILE` | Path to the GraphQL file with the new schema extension. | +| `--url ` | `NITRO_DOWNSTREAM_URL` | New URL of the downstream GraphQL service. | + +## Examples + +Replace the schema and extension files: + +```shell +nitro mock update "" \ + --schema ./schema.graphqls \ + --extension ./extension.graphql +``` + +Rename a mock schema: + +```shell +nitro mock update "" --name "" +``` + +Repoint a mock schema at a different downstream URL: + +```shell +nitro mock update "" --url "" +``` diff --git a/website/src/docs/nitro/cli/openapi.md b/website/src/docs/nitro/cli/openapi.md new file mode 100644 index 00000000000..a3f29275275 --- /dev/null +++ b/website/src/docs/nitro/cli/openapi.md @@ -0,0 +1,208 @@ +--- +title: openapi +--- + +The `nitro openapi` commands manage OpenAPI collections. An OpenAPI collection registers one or more OpenAPI documents with Nitro and tracks their versions across stages, so consumers always pick up the spec that matches the stage they target. + +A typical workflow is: `create` a collection on an API, `upload` a new version of its OpenAPI documents, 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. | +| `--api-id ` | `NITRO_API_ID` | ID of the API the collection belongs to. 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 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. | + +## Examples + +List collections for an API: + +```shell +nitro openapi list --api-id "" +``` + +Page through collections in JSON mode: + +```shell +nitro openapi list --api-id "" --output json +nitro openapi list --api-id "" --output json --cursor "" +``` + +# `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. | + +## Options + +| Option | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | + +## Examples + +Delete with confirmation: + +```shell +nitro openapi delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro openapi delete "" --force +``` + +# `nitro openapi upload` + +Upload a new version of an OpenAPI collection. OpenAPI documents are picked up via glob patterns. + +```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 the OpenAPI document files. Required. | + +## Examples + +Upload all OpenAPI documents matching a pattern: + +```shell +nitro openapi upload \ + --openapi-collection-id "" \ + --tag "v1" \ + --pattern "./**/*.yaml" +``` + +# `nitro openapi validate` + +Validate a new OpenAPI collection version against a stage without publishing it. Use this in CI to catch breaking changes before a deploy job runs. + +```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 the OpenAPI document files. Required. | + +## Examples + +Validate against the `dev` stage: + +```shell +nitro openapi validate \ + --openapi-collection-id "" \ + --stage "dev" \ + --pattern "./**/*.yaml" +``` + +# `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 +``` diff --git a/website/src/docs/nitro/cli/pat.md b/website/src/docs/nitro/cli/pat.md new file mode 100644 index 00000000000..181d2dd5375 --- /dev/null +++ b/website/src/docs/nitro/cli/pat.md @@ -0,0 +1,121 @@ +--- +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). + +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 "30" +``` + +## 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. | + +## Examples + +List your tokens: + +```shell +nitro pat list +``` + +Page through tokens in JSON mode: + +```shell +nitro pat list --output json +nitro pat list --output json --cursor "" +``` + +# `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`. | + +## Examples + +Revoke with confirmation: + +```shell +nitro pat revoke "" +``` + +Revoke in a script (no prompt): + +```shell +nitro pat revoke "" --force +``` + +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. diff --git a/website/src/docs/nitro/cli/schema.md b/website/src/docs/nitro/cli/schema.md new file mode 100644 index 00000000000..d5e8caf5800 --- /dev/null +++ b/website/src/docs/nitro/cli/schema.md @@ -0,0 +1,162 @@ +--- +title: schema +--- + +The `nitro schema` commands manage the GraphQL schema (SDL) of an API. A schema version is uploaded with a `--tag` (for example `v1` or a Git commit SHA) and can then be validated against, or published to, a stage (for example `dev`, `staging`, `production`). + +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. + +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 tagged with a Git commit: + +```shell +nitro schema upload \ + --api-id "" \ + --tag "$(git rev-parse HEAD)" \ + --schema-file ./schema.graphqls +``` + +Upload using environment variables (useful in CI): + +```shell +export NITRO_API_ID="" +export NITRO_TAG="v1" +export NITRO_SCHEMA_FILE="./schema.graphqls" +nitro schema upload +``` + +# `nitro schema validate` + +Validate a schema file against a stage without publishing it. The server returns the list of breaking, dangerous, and safe changes, plus any operations from registered clients that would break. + +```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 a `dev` stage in a pull request check: + +```shell +nitro schema validate \ + --api-id "" \ + --stage "dev" \ + --schema-file ./schema.graphqls +``` + +# `nitro schema publish` + +Publish a previously uploaded schema version to a stage. By default the publish fails if the version introduces breaking changes. Use `--force` to override, or `--wait-for-approval` to pause until a reviewer approves the change in the Nitro UI. + +```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 deploy. 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. | +| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Wait for a reviewer to approve the deployment in Nitro before completing. | + +`--force` and `--wait-for-approval` are mutually exclusive. + +## Examples + +Publish a previously uploaded version to `dev`: + +```shell +nitro schema publish \ + --api-id "" \ + --tag "" \ + --stage "dev" +``` + +Publish to `production` and wait for manual approval: + +```shell +nitro schema publish \ + --api-id "" \ + --tag "" \ + --stage "production" \ + --wait-for-approval +``` + +Force-publish a version with known breaking changes: + +```shell +nitro schema publish \ + --api-id "" \ + --tag "" \ + --stage "dev" \ + --force +``` + +# `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/stage.md b/website/src/docs/nitro/cli/stage.md new file mode 100644 index 00000000000..7a6d120996a --- /dev/null +++ b/website/src/docs/nitro/cli/stage.md @@ -0,0 +1,113 @@ +--- +title: stage +--- + +The `nitro stage` commands manage the stages of an API. Stages live inside an [environment](/docs/nitro/cli/environment) and represent deployment targets (for example `dev`, `staging`, `production`) that 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`) define the promotion order between stages. + +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. | + +## Examples + +List stages for an API: + +```shell +nitro stage list --api-id "" +``` + +Get just the stage names in a script: + +```shell +nitro stage list --api-id "" --output json | jq -r '.values[].name' +``` + +# `nitro stage delete` + +Delete a single stage by name. Deleting a stage that has published schemas, clients, or fusion configurations will fail, remove or migrate the 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. | +| `--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`. | + +## Examples + +Delete a stage with confirmation: + +```shell +nitro stage delete --stage "" --api-id "" +``` + +Delete a stage in a script (no prompt): + +```shell +nitro stage delete \ + --stage "" \ + --api-id "" \ + --force +``` diff --git a/website/src/docs/nitro/cli/status.md b/website/src/docs/nitro/cli/status.md new file mode 100644 index 00000000000..f83bd0c0047 --- /dev/null +++ b/website/src/docs/nitro/cli/status.md @@ -0,0 +1,21 @@ +--- +title: 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. + +If no session exists, the command exits with an error and instructs you to run `nitro login`. + +All `status` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +```shell +nitro status +``` + +## Examples + +Show the current session: + +```shell +nitro status +``` diff --git a/website/src/docs/nitro/cli/workspace.md b/website/src/docs/nitro/cli/workspace.md new file mode 100644 index 00000000000..51c3965c71e --- /dev/null +++ b/website/src/docs/nitro/cli/workspace.md @@ -0,0 +1,139 @@ +--- +title: workspace +--- + +The `nitro workspace` commands manage workspaces. A workspace is the top-level container in Nitro, every API, environment, member, 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. In interactive mode the CLI also asks whether to make the new workspace your default. + +```shell +nitro workspace create --name "" +``` + +## Options + +| Option | Env | 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. | + +## Examples + +Create a workspace and set it as the default: + +```shell +nitro workspace create --name "" --default +``` + +Create a workspace without changing the default: + +```shell +nitro workspace create --name "" --default false +``` + +# `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. | + +## Examples + +List workspaces: + +```shell +nitro workspace list +``` + +Page through workspaces in JSON mode: + +```shell +nitro workspace list --output json +nitro workspace list --output json --cursor "" +``` + +# `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. | + +## Examples + +Show a workspace: + +```shell +nitro workspace show "" +``` + +Read just the name in a script: + +```shell +nitro workspace show "" --output json | jq -r '.name' +``` + +# `nitro workspace current` + +Show the name of the currently selected workspace. Exits with an error if no workspace is selected. + +```shell +nitro workspace current +``` + +## Examples + +Print the current 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. | + +## Examples + +Pick a workspace interactively: + +```shell +nitro workspace set-default +``` + +Set a specific workspace as the default: + +```shell +nitro workspace set-default --workspace-id "" +``` From 3200aa2acdbf2539d20657eebc4651fee7099242 Mon Sep 17 00:00:00 2001 From: tobias-tengler <45513122+tobias-tengler@users.noreply.github.com> Date: Mon, 4 May 2026 20:59:01 +0200 Subject: [PATCH 2/5] wip --- website/src/docs/docs.json | 16 +- website/src/docs/nitro/cli/client.md | 266 +++++++++--------- website/src/docs/nitro/cli/fusion.md | 252 +++++++---------- website/src/docs/nitro/cli/global-options.md | 31 ++ website/src/docs/nitro/cli/launch.md | 17 -- website/src/docs/nitro/cli/logout.md | 17 -- website/src/docs/nitro/cli/mcp.md | 180 ++++++------ website/src/docs/nitro/cli/mock.md | 8 +- website/src/docs/nitro/cli/openapi.md | 176 ++++++------ website/src/docs/nitro/cli/pat.md | 2 +- website/src/docs/nitro/cli/schema.md | 60 ++-- .../docs/nitro/cli/{login.md => session.md} | 60 +++- website/src/docs/nitro/cli/stage.md | 4 +- website/src/docs/nitro/cli/status.md | 21 -- website/src/docs/nitro/cli/workspace.md | 2 + 15 files changed, 552 insertions(+), 560 deletions(-) create mode 100644 website/src/docs/nitro/cli/global-options.md delete mode 100644 website/src/docs/nitro/cli/launch.md delete mode 100644 website/src/docs/nitro/cli/logout.md rename website/src/docs/nitro/cli/{login.md => session.md} (53%) delete mode 100644 website/src/docs/nitro/cli/status.md diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index 3cfe8dc19a2..5a4f288ea0c 100644 --- a/website/src/docs/docs.json +++ b/website/src/docs/docs.json @@ -147,20 +147,12 @@ "title": "Installation" }, { - "path": "login", - "title": "login" - }, - { - "path": "logout", - "title": "logout" - }, - { - "path": "status", - "title": "status" + "path": "global-options", + "title": "Global Options" }, { - "path": "launch", - "title": "launch" + "path": "session", + "title": "session" }, { "path": "api", diff --git a/website/src/docs/nitro/cli/client.md b/website/src/docs/nitro/cli/client.md index 4d7a5ff494e..86eaf284fae 100644 --- a/website/src/docs/nitro/cli/client.md +++ b/website/src/docs/nitro/cli/client.md @@ -37,104 +37,6 @@ nitro client create \ --name "" ``` -# `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. | - -## Examples - -List clients for an API: - -```shell -nitro client list --api-id "" -``` - -Page through all clients in JSON mode: - -```shell -nitro client list --api-id "" --output json -nitro client list --api-id "" --output json --cursor "" -``` - -# `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. | - -## Examples - -List all versions of a client: - -```shell -nitro client list versions --client-id "" -``` - -# `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. | - -## Examples - -List published versions of a client: - -```shell -nitro client list published-versions --client-id "" -``` - -# `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. | - -## Examples - -Show a client: - -```shell -nitro client show "" -``` - # `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. @@ -165,36 +67,6 @@ nitro client upload \ --operations-file ./operations.json ``` -# `nitro client validate` - -Validate a client's operations against a stage without publishing. Returns the operations that would break against the schema currently published to the stage. - -```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 a client against the `dev` stage in a pull request check: - -```shell -nitro client validate \ - --client-id "" \ - --stage "dev" \ - --operations-file ./operations.json -``` - # `nitro client publish` Publish a previously uploaded client version to a stage. By default the publish fails if the version contains operations that break against the stage's schema. Use `--force` to override, or `--wait-for-approval` to pause until a reviewer approves the change in the Nitro UI. @@ -239,6 +111,36 @@ nitro client publish \ --wait-for-approval ``` +# `nitro client validate` + +Validate a client's operations against a stage without publishing. Returns the operations that would break against the schema currently published to the stage. + +```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 a client against the `dev` stage in a pull request check: + +```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. @@ -252,11 +154,11 @@ nitro client unpublish \ ## 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. | +| 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 @@ -320,6 +222,104 @@ nitro client download \ --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. | + +## Examples + +List clients for an API: + +```shell +nitro client list --api-id "" +``` + +Page through all clients in JSON mode: + +```shell +nitro client list --api-id "" --output json +nitro client list --api-id "" --output json --cursor "" +``` + +# `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. | + +## Examples + +List all versions of a client: + +```shell +nitro client list versions --client-id "" +``` + +# `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. | + +## Examples + +List published versions of a client: + +```shell +nitro client list published-versions --client-id "" +``` + +# `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. | + +## Examples + +Show a client: + +```shell +nitro client show "" +``` + # `nitro client delete` Delete a client by its ID. This removes the client and all of its versions. diff --git a/website/src/docs/nitro/cli/fusion.md b/website/src/docs/nitro/cli/fusion.md index a5eca6f3a5c..dd8d0b95677 100644 --- a/website/src/docs/nitro/cli/fusion.md +++ b/website/src/docs/nitro/cli/fusion.md @@ -6,7 +6,38 @@ The `nitro fusion` commands manage [Fusion](/docs/fusion), ChilliCream's federat The most common workflow is `compose` locally, then `publish` to a stage. `nitro fusion publish` runs the full publishing flow (validate, start, commit) in a single command and is the right choice for almost every pipeline. -> Local commands like `compose`, `migrate`, `run`, and `settings set` operate on archive files on disk and do not require authentication. Every other `fusion` command requires authentication, run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). +> Local commands like `compose`, `run`, and `settings set` operate on archive files on disk and do not require authentication. Every other `fusion` command requires authentication, run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). + +# `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. | + +## Examples + +Upload a single source schema: + +```shell +nitro fusion upload \ + --api-id "" \ + --tag "v1" \ + --source-schema-file ./products/schema.graphqls +``` # `nitro fusion publish` @@ -147,56 +178,46 @@ nitro fusion publish cancel --request-id "" | --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------- | | `--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 compose` +# `nitro fusion validate` -Compose multiple source schemas into a single composite schema and write the result to a Fusion archive. This is the local equivalent of the composition step that `publish` performs, and is useful for inspecting the composed schema or staging an archive before publishing. +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 compose \ - --source-schema-file "" \ +nitro fusion validate \ + --api-id "" \ + --stage "" \ --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. | +| 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. | ## 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: +Validate a pre-composed archive: ```shell -nitro fusion compose \ - --working-directory ./subgraphs \ +nitro fusion validate \ + --api-id "" \ + --stage "dev" \ --archive ./gateway.far ``` -Recompose on file changes during local development: +Validate by composing source schemas on the fly: ```shell -nitro fusion compose \ +nitro fusion validate \ + --api-id "" \ + --stage "dev" \ --source-schema-file ./products/schema.graphqls \ - --archive ./gateway.far \ - --watch + --source-schema-file ./reviews/schema.graphqls ``` # `nitro fusion download` @@ -230,139 +251,56 @@ nitro fusion download \ --output-file ./gateway.far ``` -# `nitro fusion migrate` - -Migrate Fusion configuration files from a legacy format to the current format. Use this once when upgrading an existing Fusion v1 setup. - -```shell -nitro fusion migrate -``` - -## Arguments - -| Argument | Description | -| ------------------- | -------------------------------------------------------------------------- | -| `` | Migration target. Currently the only supported value is `subgraph-config`. | - -## Options - -| Option | Description | -| --------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| `-w, --working-directory ` | Working directory the command searches for files to migrate. Defaults to the current directory. | - -## Examples - -Migrate `subgraph-config.json` files in the current directory: - -```shell -nitro fusion migrate subgraph-config -``` - -Migrate files in a specific directory: - -```shell -nitro fusion migrate subgraph-config --working-directory ./gateway -``` - -# `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 ` | Port the gateway will listen on. When omitted, the default port is used. | - -## Examples - -Run a gateway on port 5000: - -```shell -nitro fusion run ./gateway.far --port 5000 -``` - -# `nitro fusion upload` +# `nitro fusion compose` -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`). +Compose multiple source schemas into a single composite schema and write the result to a Fusion archive. This is the local equivalent of the composition step that `publish` performs, and is useful for inspecting the composed schema or staging an archive before publishing. ```shell -nitro fusion upload \ - --api-id "" \ - --tag "" \ - --source-schema-file "" +nitro fusion compose \ + --source-schema-file "" \ + --archive "" ``` ## 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. | +| 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. | ## Examples -Upload a single source schema: - -```shell -nitro fusion upload \ - --api-id "" \ - --tag "v1" \ - --source-schema-file ./products/schema.graphqls -``` - -# `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. +Compose a gateway from two source schemas: ```shell -nitro fusion validate \ - --api-id "" \ - --stage "" \ - --archive "" +nitro fusion compose \ + --source-schema-file ./products/schema.graphqls \ + --source-schema-file ./reviews/schema.graphqls \ + --archive ./gateway.far \ + --env "dev" ``` -## 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. | - -## Examples - -Validate a pre-composed archive: +Auto-discover source schemas from a working directory: ```shell -nitro fusion validate \ - --api-id "" \ - --stage "dev" \ +nitro fusion compose \ + --working-directory ./subgraphs \ --archive ./gateway.far ``` -Validate by composing source schemas on the fly: +Recompose on file changes during local development: ```shell -nitro fusion validate \ - --api-id "" \ - --stage "dev" \ +nitro fusion compose \ --source-schema-file ./products/schema.graphqls \ - --source-schema-file ./reviews/schema.graphqls + --archive ./gateway.far \ + --watch ``` # `nitro fusion settings set` @@ -397,3 +335,31 @@ 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 new file mode 100644 index 00000000000..f690528a41a --- /dev/null +++ b/website/src/docs/nitro/cli/global-options.md @@ -0,0 +1,31 @@ +--- +title: Global Options +--- + +Every `nitro` command supports these options. They control where the CLI talks to, how it authenticates, and how output is formatted. Per-command docs don't repeat them, refer back here. + +> The `--api-key` flag accepts both API keys (created via `nitro api-key create`) and Personal Access Tokens (created via `nitro pat create`). For interactive use, prefer `nitro login` instead. + +# `--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. + +Set via the `NITRO_CLOUD_URL` environment variable. Defaults to `api.chillicream.com`. + +# `--api-key ` + +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). + +Set via the `NITRO_API_KEY` environment variable. For interactive use, prefer `nitro login` over passing this flag. + +# `--output ` + +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. + +# `-?, -h, --help` + +Show help and usage information for the command. Use this on any subcommand to see its options, environment variables, and an example invocation. diff --git a/website/src/docs/nitro/cli/launch.md b/website/src/docs/nitro/cli/launch.md deleted file mode 100644 index c5513e200ca..00000000000 --- a/website/src/docs/nitro/cli/launch.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: launch ---- - -The `nitro launch` command opens the Nitro web UI in your default browser. It's a convenience shortcut, useful for jumping from the terminal into the UI to create a workspace, browse APIs, or inspect telemetry. - -```shell -nitro launch -``` - -## Examples - -Open the Nitro web UI: - -```shell -nitro launch -``` diff --git a/website/src/docs/nitro/cli/logout.md b/website/src/docs/nitro/cli/logout.md deleted file mode 100644 index a5542e0ef41..00000000000 --- a/website/src/docs/nitro/cli/logout.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 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` (see [Global Options](/docs/nitro/cli/global-options)). - -```shell -nitro logout -``` - -## Examples - -Log out of the current session: - -```shell -nitro logout -``` diff --git a/website/src/docs/nitro/cli/mcp.md b/website/src/docs/nitro/cli/mcp.md index b414ad6410d..7fa2251f437 100644 --- a/website/src/docs/nitro/cli/mcp.md +++ b/website/src/docs/nitro/cli/mcp.md @@ -22,10 +22,10 @@ nitro mcp create \ ## Options -| Option | Env | Description | -| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ | -| `--name ` | `NITRO_MCP_FEATURE_COLLECTION_NAME` | Display name of the MCP feature collection. | -| `--api-id ` | `NITRO_API_ID` | ID of the API the collection belongs to. Get the ID from `nitro api list` or the Nitro UI. | +| 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 @@ -41,101 +41,79 @@ Create a collection non-interactively: nitro mcp create --name "" --api-id "" ``` -# `nitro mcp list` +# `nitro mcp upload` -List all MCP feature collections of an API. Results are paginated, use the returned cursor to fetch the next page. +Upload a new version of an MCP feature collection. Prompt and tool definition files are picked up via glob patterns. ```shell -nitro mcp list --api-id "" +nitro mcp upload \ + --mcp-feature-collection-id "" \ + --tag "" \ + --prompt-pattern "" \ + --tool-pattern "" ``` ## 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. | +| 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 -List collections for an API: - -```shell -nitro mcp list --api-id "" -``` - -Page through collections in JSON mode: +Upload prompts and tools from the default folders: ```shell -nitro mcp list --api-id "" --output json -nitro mcp list --api-id "" --output json --cursor "" +nitro mcp upload \ + --mcp-feature-collection-id "" \ + --tag "v1" \ + --prompt-pattern "./prompts/**/*.json" \ + --tool-pattern "./tools/**/*.graphql" ``` -# `nitro mcp delete` +# `nitro mcp publish` -Delete an MCP feature collection by its ID. Once deleted, the collection and all its versions are no longer accessible to MCP clients. +Publish a previously uploaded MCP feature collection version to a stage. The version is identified by its tag. ```shell -nitro mcp delete "" +nitro mcp publish \ + --mcp-feature-collection-id "" \ + --tag "" \ + --stage "" ``` -## Arguments - -| Argument | Description | -| -------- | ------------------------------------------- | -| `` | ID of the MCP feature collection to delete. | - ## Options -| Option | Description | -| --------- | --------------------------------------------------------------------------------------------------------------------------- | -| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | +| 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 -Delete with confirmation: - -```shell -nitro mcp delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro mcp delete "" --force -``` - -# `nitro mcp upload` - -Upload a new version of an MCP feature collection. Prompt and tool definition files are picked up via glob patterns. +Publish to `dev`: ```shell -nitro mcp upload \ +nitro mcp publish \ --mcp-feature-collection-id "" \ - --tag "" \ - --prompt-pattern "" \ - --tool-pattern "" + --stage "dev" \ + --tag "v1" ``` -## 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: +Publish to a gated stage and wait for approval: ```shell -nitro mcp upload \ +nitro mcp publish \ --mcp-feature-collection-id "" \ + --stage "production" \ --tag "v1" \ - --prompt-pattern "./prompts/**/*.json" \ - --tool-pattern "./tools/**/*.graphql" + --wait-for-approval ``` # `nitro mcp validate` @@ -171,44 +149,66 @@ nitro mcp validate \ --tool-pattern "./tools/**/*.graphql" ``` -# `nitro mcp publish` +# `nitro mcp list` -Publish a previously uploaded MCP feature collection version to a stage. The version is identified by its tag. +List all MCP feature collections of an API. Results are paginated, use the returned cursor to fetch the next page. ```shell -nitro mcp publish \ - --mcp-feature-collection-id "" \ - --tag "" \ - --stage "" +nitro mcp list --api-id "" ``` ## 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. | +| 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. | ## Examples -Publish to `dev`: +List collections for an API: ```shell -nitro mcp publish \ - --mcp-feature-collection-id "" \ - --stage "dev" \ - --tag "v1" +nitro mcp list --api-id "" ``` -Publish to a gated stage and wait for approval: +Page through collections in JSON mode: ```shell -nitro mcp publish \ - --mcp-feature-collection-id "" \ - --stage "production" \ - --tag "v1" \ - --wait-for-approval +nitro mcp list --api-id "" --output json +nitro mcp list --api-id "" --output json --cursor "" +``` + +# `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`. | + +## Examples + +Delete with confirmation: + +```shell +nitro mcp delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro mcp delete "" --force ``` diff --git a/website/src/docs/nitro/cli/mock.md b/website/src/docs/nitro/cli/mock.md index b672a096043..6c9ef711c96 100644 --- a/website/src/docs/nitro/cli/mock.md +++ b/website/src/docs/nitro/cli/mock.md @@ -26,10 +26,10 @@ nitro mock create \ | Option | Env | Description | | ------------------------- | ----------------------------- | ---------------------------------------------------------------------------------- | | `--api-id ` | `NITRO_API_ID` | ID of the API to attach the mock schema to. | -| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | Display name of the mock schema. Required. | -| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the base schema. Required. | | `--extension ` | `NITRO_SCHEMA_EXTENSION_FILE` | Path to the GraphQL file with the schema extension. Required. | +| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the base schema. Required. | | `--url ` | `NITRO_DOWNSTREAM_URL` | URL of the downstream GraphQL service that real fields are forwarded to. Required. | +| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | Display name of the mock schema. Required. | ## Examples @@ -94,10 +94,10 @@ nitro mock update "" \ | Option | Env | Description | | ------------------------- | ----------------------------- | ------------------------------------------------------- | -| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | New display name of the mock schema. | -| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the new base schema. | | `--extension ` | `NITRO_SCHEMA_EXTENSION_FILE` | Path to the GraphQL file with the new schema extension. | +| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the new base schema. | | `--url ` | `NITRO_DOWNSTREAM_URL` | New URL of the downstream GraphQL service. | +| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | New display name of the mock schema. | ## Examples diff --git a/website/src/docs/nitro/cli/openapi.md b/website/src/docs/nitro/cli/openapi.md index a3f29275275..02cf369b787 100644 --- a/website/src/docs/nitro/cli/openapi.md +++ b/website/src/docs/nitro/cli/openapi.md @@ -22,10 +22,10 @@ nitro openapi create \ ## Options -| Option | Env | Description | -| ------------------- | ------------------------------- | ------------------------------------------------------------------------------------------ | -| `--name ` | `NITRO_OPENAPI_COLLECTION_NAME` | Display name of the OpenAPI collection. | -| `--api-id ` | `NITRO_API_ID` | ID of the API the collection belongs to. Get the ID from `nitro api list` or the Nitro UI. | +| 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 @@ -41,98 +41,76 @@ Create a collection non-interactively: nitro openapi create --name "" --api-id "" ``` -# `nitro openapi list` +# `nitro openapi upload` -List all OpenAPI collections of an API. Results are paginated, use the returned cursor to fetch the next page. +Upload a new version of an OpenAPI collection. OpenAPI documents are picked up via glob patterns. ```shell -nitro openapi list --api-id "" +nitro openapi upload \ + --openapi-collection-id "" \ + --tag "" \ + --pattern "" ``` ## 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. | +| 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 the OpenAPI document files. Required. | ## Examples -List collections for an API: - -```shell -nitro openapi list --api-id "" -``` - -Page through collections in JSON mode: +Upload all OpenAPI documents matching a pattern: ```shell -nitro openapi list --api-id "" --output json -nitro openapi list --api-id "" --output json --cursor "" +nitro openapi upload \ + --openapi-collection-id "" \ + --tag "v1" \ + --pattern "./**/*.graphql" ``` -# `nitro openapi delete` +# `nitro openapi publish` -Delete an OpenAPI collection by its ID. Once deleted, the collection and all its versions are no longer accessible. +Publish a previously uploaded OpenAPI collection version to a stage. The version is identified by its tag. ```shell -nitro openapi delete "" +nitro openapi publish \ + --openapi-collection-id "" \ + --tag "" \ + --stage "" ``` -## Arguments - -| Argument | Description | -| -------- | --------------------------------------- | -| `` | ID of the OpenAPI collection to delete. | - ## Options -| Option | Description | -| --------- | --------------------------------------------------------------------------------------------------------------------------- | -| `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | +| 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 -Delete with confirmation: - -```shell -nitro openapi delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro openapi delete "" --force -``` - -# `nitro openapi upload` - -Upload a new version of an OpenAPI collection. OpenAPI documents are picked up via glob patterns. +Publish to `dev`: ```shell -nitro openapi upload \ +nitro openapi publish \ --openapi-collection-id "" \ - --tag "" \ - --pattern "" + --stage "dev" \ + --tag "v1" ``` -## 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 the OpenAPI document files. Required. | - -## Examples - -Upload all OpenAPI documents matching a pattern: +Publish to a gated stage and wait for approval: ```shell -nitro openapi upload \ +nitro openapi publish \ --openapi-collection-id "" \ + --stage "production" \ --tag "v1" \ - --pattern "./**/*.yaml" + --wait-for-approval ``` # `nitro openapi validate` @@ -162,47 +140,69 @@ Validate against the `dev` stage: nitro openapi validate \ --openapi-collection-id "" \ --stage "dev" \ - --pattern "./**/*.yaml" + --pattern "./**/*.graphql" ``` -# `nitro openapi publish` +# `nitro openapi list` -Publish a previously uploaded OpenAPI collection version to a stage. The version is identified by its tag. +List all OpenAPI collections of an API. Results are paginated, use the returned cursor to fetch the next page. ```shell -nitro openapi publish \ - --openapi-collection-id "" \ - --tag "" \ - --stage "" +nitro openapi list --api-id "" ``` ## 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. | +| 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. | ## Examples -Publish to `dev`: +List collections for an API: ```shell -nitro openapi publish \ - --openapi-collection-id "" \ - --stage "dev" \ - --tag "v1" +nitro openapi list --api-id "" ``` -Publish to a gated stage and wait for approval: +Page through collections in JSON mode: ```shell -nitro openapi publish \ - --openapi-collection-id "" \ - --stage "production" \ - --tag "v1" \ - --wait-for-approval +nitro openapi list --api-id "" --output json +nitro openapi list --api-id "" --output json --cursor "" +``` + +# `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`. | + +## Examples + +Delete with confirmation: + +```shell +nitro openapi delete "" +``` + +Delete in a script (no prompt): + +```shell +nitro openapi delete "" --force ``` diff --git a/website/src/docs/nitro/cli/pat.md b/website/src/docs/nitro/cli/pat.md index 181d2dd5375..ec5f317a22a 100644 --- a/website/src/docs/nitro/cli/pat.md +++ b/website/src/docs/nitro/cli/pat.md @@ -17,7 +17,7 @@ Create a new personal access token. The secret is returned only once at creation ```shell nitro pat create \ --description "" \ - --expires "30" + --expires "" ``` ## Options diff --git a/website/src/docs/nitro/cli/schema.md b/website/src/docs/nitro/cli/schema.md index d5e8caf5800..a5f64b62873 100644 --- a/website/src/docs/nitro/cli/schema.md +++ b/website/src/docs/nitro/cli/schema.md @@ -47,36 +47,6 @@ export NITRO_SCHEMA_FILE="./schema.graphqls" nitro schema upload ``` -# `nitro schema validate` - -Validate a schema file against a stage without publishing it. The server returns the list of breaking, dangerous, and safe changes, plus any operations from registered clients that would break. - -```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 a `dev` stage in a pull request check: - -```shell -nitro schema validate \ - --api-id "" \ - --stage "dev" \ - --schema-file ./schema.graphqls -``` - # `nitro schema publish` Publish a previously uploaded schema version to a stage. By default the publish fails if the version introduces breaking changes. Use `--force` to override, or `--wait-for-approval` to pause until a reviewer approves the change in the Nitro UI. @@ -131,6 +101,36 @@ nitro schema publish \ --force ``` +# `nitro schema validate` + +Validate a schema file against a stage without publishing it. The server returns the list of breaking, dangerous, and safe changes, plus any operations from registered clients that would break. + +```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 a `dev` stage in a pull request check: + +```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. diff --git a/website/src/docs/nitro/cli/login.md b/website/src/docs/nitro/cli/session.md similarity index 53% rename from website/src/docs/nitro/cli/login.md rename to website/src/docs/nitro/cli/session.md index dd0486c1f42..b0a53e5a20b 100644 --- a/website/src/docs/nitro/cli/login.md +++ b/website/src/docs/nitro/cli/session.md @@ -1,11 +1,15 @@ --- -title: login +title: session --- -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`. +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 ``` @@ -41,3 +45,55 @@ Log in against a self-hosted or dedicated deployment using the option: ```shell nitro login --cloud-url "" ``` + +# `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 +``` + +## Examples + +Log out of the current session: + +```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. + +If no session exists, the command exits with an error and instructs you to run `nitro login`. + +The `status` command requires authentication. Run `nitro login` first or pass `--api-key`. + +```shell +nitro status +``` + +## Examples + +Show the current session: + +```shell +nitro status +``` + +# `nitro launch` + +The `nitro launch` command opens the Nitro web UI in your default browser. It's a convenience shortcut, useful for jumping from the terminal into the UI to create a workspace, browse APIs, or inspect telemetry. + +```shell +nitro launch +``` + +## Examples + +Open the Nitro web UI: + +```shell +nitro launch +``` diff --git a/website/src/docs/nitro/cli/stage.md b/website/src/docs/nitro/cli/stage.md index 7a6d120996a..60167705fb3 100644 --- a/website/src/docs/nitro/cli/stage.md +++ b/website/src/docs/nitro/cli/stage.md @@ -79,7 +79,7 @@ nitro stage list --api-id "" --output json | jq -r '.values[].name' # `nitro stage delete` -Delete a single stage by name. Deleting a stage that has published schemas, clients, or fusion configurations will fail, remove or migrate the dependencies first. +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 \ @@ -91,7 +91,7 @@ nitro stage delete \ | Option | Env | Description | | ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `--api-id ` | `NITRO_API_ID` | ID of the API the stage belongs to. | +| `--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/status.md b/website/src/docs/nitro/cli/status.md deleted file mode 100644 index f83bd0c0047..00000000000 --- a/website/src/docs/nitro/cli/status.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 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. - -If no session exists, the command exits with an error and instructs you to run `nitro login`. - -All `status` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). - -```shell -nitro status -``` - -## Examples - -Show the current session: - -```shell -nitro status -``` diff --git a/website/src/docs/nitro/cli/workspace.md b/website/src/docs/nitro/cli/workspace.md index 51c3965c71e..b30f7096435 100644 --- a/website/src/docs/nitro/cli/workspace.md +++ b/website/src/docs/nitro/cli/workspace.md @@ -23,6 +23,8 @@ nitro workspace create --name "" | `--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. + ## Examples Create a workspace and set it as the default: From b6598e61d805f2142bee4897bd6fc5664571a311 Mon Sep 17 00:00:00 2001 From: tobias-tengler <45513122+tobias-tengler@users.noreply.github.com> Date: Wed, 6 May 2026 16:04:32 +0200 Subject: [PATCH 3/5] wip --- .../Commands/Launch/LaunchCommand.cs | 31 ++++- .../Extensions/ServiceCollectionExtensions.cs | 3 + .../src/CommandLine/Helpers/Constants.cs | 3 - .../CommandLine/Helpers/IBrowserLauncher.cs | 6 + .../Helpers/SystemBrowserLauncher.cs | 6 + .../Options/BaseSchemaFileOption.cs | 2 +- .../Options/EnvironmentVariables.cs | 2 + .../Options/ExtensionFileOption.cs | 2 +- .../CommandLine/Options/SchemaFileOption.cs | 2 +- .../Commands/CommandTestBase.cs | 2 + .../Commands/Session/LaunchCommandTests.cs | 95 ++++++++++++++ website/src/docs/nitro/cli/api-key.md | 37 +----- website/src/docs/nitro/cli/api.md | 51 +------- website/src/docs/nitro/cli/client.md | 117 +++++------------ website/src/docs/nitro/cli/environment.md | 33 +---- website/src/docs/nitro/cli/fusion.md | 77 ++++++----- website/src/docs/nitro/cli/global-options.md | 16 +-- website/src/docs/nitro/cli/installation.md | 63 ++++++++- website/src/docs/nitro/cli/mcp.md | 33 +---- website/src/docs/nitro/cli/mock.md | 122 ------------------ website/src/docs/nitro/cli/openapi.md | 35 +---- website/src/docs/nitro/cli/pat.md | 33 +---- website/src/docs/nitro/cli/schema.md | 57 +++----- website/src/docs/nitro/cli/session.md | 40 +----- website/src/docs/nitro/cli/stage.md | 35 +---- website/src/docs/nitro/cli/workspace.md | 79 +----------- 26 files changed, 324 insertions(+), 658 deletions(-) create mode 100644 src/Nitro/CommandLine/src/CommandLine/Helpers/IBrowserLauncher.cs create mode 100644 src/Nitro/CommandLine/src/CommandLine/Helpers/SystemBrowserLauncher.cs create mode 100644 src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Session/LaunchCommandTests.cs delete mode 100644 website/src/docs/nitro/cli/mock.md diff --git a/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs b/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs index 4a59dca5fd3..f08bae806bf 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}]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/nitro/cli/api-key.md b/website/src/docs/nitro/cli/api-key.md index eb713ed77dc..a5627532479 100644 --- a/website/src/docs/nitro/cli/api-key.md +++ b/website/src/docs/nitro/cli/api-key.md @@ -6,7 +6,7 @@ The `nitro api-key` commands manage API keys. API keys authenticate non-interact 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 (Preview). This lets you issue, for example, a `production`-only key that cannot publish to `dev`. +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. @@ -41,12 +41,6 @@ Create an API-scoped key: nitro api-key create --name "" --api-id "" ``` -Create a workspace-scoped key (uses the workspace from your session): - -```shell -nitro api-key create --name "" -``` - Create a workspace-scoped key with an explicit workspace: ```shell @@ -86,21 +80,6 @@ nitro api-key list | `--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. | -## Examples - -List keys in the current workspace: - -```shell -nitro api-key list -``` - -Page through all keys in JSON mode: - -```shell -nitro api-key list --output json -nitro api-key list --output json --cursor "" -``` - # `nitro api-key delete` Delete an API key by its ID. Once deleted, any client using the key loses access immediately. @@ -120,17 +99,3 @@ nitro api-key delete "" | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | - -## Examples - -Delete with confirmation: - -```shell -nitro api-key delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro api-key delete "" --force -``` diff --git a/website/src/docs/nitro/cli/api.md b/website/src/docs/nitro/cli/api.md index d3c63c2e98d..5d34d45686e 100644 --- a/website/src/docs/nitro/cli/api.md +++ b/website/src/docs/nitro/cli/api.md @@ -2,7 +2,7 @@ title: api --- -The `nitro api` commands manage APIs in a workspace. An API represents a single GraphQL endpoint that you publish schemas and clients to. APIs live under a workspace and are addressed by a path (for example `/products/catalog`). +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. @@ -68,27 +68,6 @@ nitro api list | `--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. | -## Examples - -List APIs in the current workspace: - -```shell -nitro api list -``` - -List APIs in an explicit workspace: - -```shell -nitro api list --workspace-id "" -``` - -Page through all APIs in JSON mode: - -```shell -nitro api list --output json -nitro api list --output json --cursor "" -``` - # `nitro api show` Show the details of a single API by its ID. @@ -103,20 +82,6 @@ nitro api show "" | -------- | -------------------------------- | | `` | ID of the API to show. Required. | -## Examples - -Show an API: - -```shell -nitro api show "" -``` - -Capture the API details in a script: - -```shell -nitro api show "" --output json -``` - # `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. @@ -179,17 +144,3 @@ nitro api delete "" | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | - -## Examples - -Delete with confirmation: - -```shell -nitro api delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro api delete "" --force -``` diff --git a/website/src/docs/nitro/cli/client.md b/website/src/docs/nitro/cli/client.md index 86eaf284fae..4d7460cc350 100644 --- a/website/src/docs/nitro/cli/client.md +++ b/website/src/docs/nitro/cli/client.md @@ -2,9 +2,9 @@ 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. Registering a client lets Nitro detect when a schema change would break an operation that real consumers depend on. +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, and `validate` runs the same breaking-change detection that `publish` does without committing the result. +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)). @@ -14,27 +14,29 @@ Create a new client under an API. ```shell nitro client create \ - --api-id "" \ - --name "" + --name "" \ + --api-id "" ``` ## Options -| Option | Env | Description | -| ------------------- | ------------------- | -------------------------------------- | -| `--api-id ` | `NITRO_API_ID` | ID of the API to attach the client to. | -| `--name ` | `NITRO_CLIENT_NAME` | Display name of the client. | - -When run interactively, the CLI prompts for any option you omit. Both options are required when running non-interactively. +| 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 \ - --api-id "" \ - --name "" +nitro client create --name "" --api-id "" ``` # `nitro client upload` @@ -58,18 +60,18 @@ nitro client upload \ ## Examples -Upload a client version tagged with a Git commit: +Upload a client version: ```shell nitro client upload \ --client-id "" \ - --tag "$(git rev-parse HEAD)" \ + --tag "v1" \ --operations-file ./operations.json ``` # `nitro client publish` -Publish a previously uploaded client version to a stage. By default the publish fails if the version contains operations that break against the stage's schema. Use `--force` to override, or `--wait-for-approval` to pause until a reviewer approves the change in the Nitro UI. +Publish a previously uploaded client version to a stage. The version is identified by its tag. ```shell nitro client publish \ @@ -80,40 +82,38 @@ nitro client publish \ ## Options -| Option | Env | Description | -| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------- | -| `--client-id ` | `NITRO_CLIENT_ID` | ID of the client. Required. | -| `--tag ` | `NITRO_TAG` | Tag of the client version to deploy. 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. | -| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Wait for a reviewer to approve the deployment in Nitro before completing. | - -`--force` and `--wait-for-approval` are mutually exclusive. +| 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 a client version to `dev`: +Publish to `dev`: ```shell nitro client publish \ --client-id "" \ - --tag "" \ + --tag "v1" \ --stage "dev" ``` -Publish to `production` and wait for manual approval: +Publish to a gated stage and wait for approval: ```shell nitro client publish \ --client-id "" \ - --tag "" \ + --tag "v1" \ --stage "production" \ --wait-for-approval ``` # `nitro client validate` -Validate a client's operations against a stage without publishing. Returns the operations that would break against the schema currently published to the stage. +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 \ @@ -132,7 +132,7 @@ nitro client validate \ ## Examples -Validate a client against the `dev` stage in a pull request check: +Validate against the `dev` stage: ```shell nitro client validate \ @@ -183,7 +183,7 @@ nitro client unpublish \ # `nitro client download` -Download the persisted operations of the client version currently published to a stage. Writes either a single JSON file (Relay-style) or a directory with one `.graphql` file per operation. +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 \ @@ -237,21 +237,6 @@ nitro client list --api-id "" | `--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. | -## Examples - -List clients for an API: - -```shell -nitro client list --api-id "" -``` - -Page through all clients in JSON mode: - -```shell -nitro client list --api-id "" --output json -nitro client list --api-id "" --output json --cursor "" -``` - # `nitro client list versions` List all versions of a client, including ones that have never been published to a stage. @@ -267,14 +252,6 @@ nitro client list versions --client-id "" | `--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. | -## Examples - -List all versions of a client: - -```shell -nitro client list versions --client-id "" -``` - # `nitro client list published-versions` List only the versions of a client that are currently published to at least one stage. @@ -290,14 +267,6 @@ nitro client list published-versions --client-id "" | `--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. | -## Examples - -List published versions of a client: - -```shell -nitro client list published-versions --client-id "" -``` - # `nitro client show` Show the details of a single client by its ID. @@ -312,14 +281,6 @@ nitro client show "" | -------- | ----------------------------------- | | `` | ID of the client to show. Required. | -## Examples - -Show a client: - -```shell -nitro client show "" -``` - # `nitro client delete` Delete a client by its ID. This removes the client and all of its versions. @@ -339,17 +300,3 @@ nitro client delete "" | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | - -## Examples - -Delete with confirmation: - -```shell -nitro client delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro client delete "" --force -``` diff --git a/website/src/docs/nitro/cli/environment.md b/website/src/docs/nitro/cli/environment.md index 57bfb7059c2..575e1edc4f4 100644 --- a/website/src/docs/nitro/cli/environment.md +++ b/website/src/docs/nitro/cli/environment.md @@ -2,9 +2,9 @@ title: environment --- -The `nitro environment` commands manage environments. An environment is a workspace-level grouping that holds named [stages](/docs/nitro/cli/stage) (for example `dev`, `staging`, `production`) and is shared across the APIs in the workspace. + -Environments let you align stage names across APIs so promotions, telemetry, and access policies use a consistent vocabulary. Stages themselves are configured per API via `nitro stage edit`. +The `nitro environment` commands manage environments. An environment is a workspace-level grouping that holds named [stages](/docs/nitro/cli/stage) (for example `dev`, `staging`, `production`) and is shared across the APIs in the workspace. All `environment` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). @@ -56,21 +56,6 @@ nitro environment list | `--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. | -## Examples - -List environments in the current workspace: - -```shell -nitro environment list -``` - -Page through environments in JSON mode: - -```shell -nitro environment list --output json -nitro environment list --output json --cursor "" -``` - # `nitro environment show` Show the details of an environment by its ID. @@ -84,17 +69,3 @@ nitro environment show "" | Argument | Description | | -------- | ---------------------------------------- | | `` | ID of the environment to show. Required. | - -## Examples - -Show an environment: - -```shell -nitro environment show "" -``` - -Get the workspace name for an environment in a script: - -```shell -WORKSPACE=$(nitro environment show "" --output json | jq -r '.workspace.name') -``` diff --git a/website/src/docs/nitro/cli/fusion.md b/website/src/docs/nitro/cli/fusion.md index dd8d0b95677..86417ff3f0b 100644 --- a/website/src/docs/nitro/cli/fusion.md +++ b/website/src/docs/nitro/cli/fusion.md @@ -2,11 +2,7 @@ title: fusion --- -The `nitro fusion` commands manage [Fusion](/docs/fusion), ChilliCream's federated GraphQL gateway. A Fusion configuration is the composed gateway artifact (a `.far` archive) built from one or more source schemas. Once published to a stage, the gateway loads it and starts serving the federated graph. - -The most common workflow is `compose` locally, then `publish` to a stage. `nitro fusion publish` runs the full publishing flow (validate, start, commit) in a single command and is the right choice for almost every pipeline. - -> Local commands like `compose`, `run`, and `settings set` operate on archive files on disk and do not require authentication. Every other `fusion` command requires authentication, run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). +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` @@ -28,6 +24,8 @@ nitro fusion upload \ | `-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: @@ -41,6 +39,8 @@ nitro fusion upload \ # `nitro fusion publish` + + Publish a Fusion configuration to a stage. This is the one-shot command that runs validation, requests a deployment slot, and commits the new configuration in sequence. ```shell @@ -66,16 +66,19 @@ nitro fusion publish \ | `--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 -Publish a pre-composed archive: +Compose and publish from previously uploaded source schemas: ```shell nitro fusion publish \ --api-id "" \ --stage "dev" \ --tag "v1" \ - --archive ./gateway.far + --source-schema products \ + --source-schema reviews ``` Compose and publish from local source schema files in one step: @@ -89,22 +92,21 @@ nitro fusion publish \ --source-schema-file ./reviews/schema.graphqls ``` -Compose and publish from previously uploaded source schemas: +Publish a pre-composed archive: ```shell nitro fusion publish \ --api-id "" \ --stage "dev" \ --tag "v1" \ - --source-schema products \ - --source-schema reviews + --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 shell). The standard order is `begin` → `validate` → `start` → `commit`. `cancel` releases the slot at any time before `commit`. +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` @@ -124,9 +126,21 @@ nitro fusion publish begin \ | `--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 the schema and clients on the stage targeted by the request. +Validate a composed Fusion archive against everything currently published to the stage targeted by the request. ```shell nitro fusion publish validate \ @@ -139,18 +153,6 @@ nitro fusion publish validate \ | `--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 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 commit` Commit the Fusion configuration, finalizing the publish. After this step the new configuration is live on the stage. @@ -199,25 +201,27 @@ nitro fusion validate \ | `--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 a pre-composed archive: +Validate by composing source schemas on the fly: ```shell nitro fusion validate \ --api-id "" \ --stage "dev" \ - --archive ./gateway.far + --source-schema-file ./products/schema.graphqls \ + --source-schema-file ./reviews/schema.graphqls ``` -Validate by composing source schemas on the fly: +Validate a pre-composed archive: ```shell nitro fusion validate \ --api-id "" \ --stage "dev" \ - --source-schema-file ./products/schema.graphqls \ - --source-schema-file ./reviews/schema.graphqls + --archive ./gateway.far ``` # `nitro fusion download` @@ -237,7 +241,7 @@ nitro fusion download \ | ----------------------------- | ------------------- | ----------------------------------------------------------------------------------- | | `--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 `2.0.0`. | +| `--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 @@ -253,7 +257,7 @@ nitro fusion download \ # `nitro fusion compose` -Compose multiple source schemas into a single composite schema and write the result to a Fusion archive. This is the local equivalent of the composition step that `publish` performs, and is useful for inspecting the composed schema or staging an archive before publishing. +Compose multiple source schemas into a single composite schema and write the result to a Fusion archive. ```shell nitro fusion compose \ @@ -274,6 +278,8 @@ nitro fusion compose \ | `-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: @@ -294,15 +300,6 @@ nitro fusion compose \ --archive ./gateway.far ``` -Recompose on file changes during local development: - -```shell -nitro fusion compose \ - --source-schema-file ./products/schema.graphqls \ - --archive ./gateway.far \ - --watch -``` - # `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. diff --git a/website/src/docs/nitro/cli/global-options.md b/website/src/docs/nitro/cli/global-options.md index f690528a41a..967d51a31e6 100644 --- a/website/src/docs/nitro/cli/global-options.md +++ b/website/src/docs/nitro/cli/global-options.md @@ -2,15 +2,9 @@ title: Global Options --- -Every `nitro` command supports these options. They control where the CLI talks to, how it authenticates, and how output is formatted. Per-command docs don't repeat them, refer back here. - -> The `--api-key` flag accepts both API keys (created via `nitro api-key create`) and Personal Access Tokens (created via `nitro pat create`). For interactive use, prefer `nitro login` instead. - -# `--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. +# `-?, -h, --help` -Set via the `NITRO_CLOUD_URL` environment variable. Defaults to `api.chillicream.com`. +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 ` @@ -26,6 +20,8 @@ Setting `--output json` also enables non-interactive mode: prompts are disabled Set via the `NITRO_OUTPUT_FORMAT` environment variable. -# `-?, -h, --help` +# `--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. +URL of the Nitro backend the CLI talks to. Only needed for self-hosted or dedicated deployments, the public ChilliCream Cloud is the default. + +Set via the `NITRO_CLOUD_URL` environment variable. Defaults to `api.chillicream.com`. diff --git a/website/src/docs/nitro/cli/installation.md b/website/src/docs/nitro/cli/installation.md index baf91f3e029..c32120d247c 100644 --- a/website/src/docs/nitro/cli/installation.md +++ b/website/src/docs/nitro/cli/installation.md @@ -2,4 +2,65 @@ title: Installation --- -TODO + + +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`. Pin the version with `@latest` 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 index 7fa2251f437..ee70657deec 100644 --- a/website/src/docs/nitro/cli/mcp.md +++ b/website/src/docs/nitro/cli/mcp.md @@ -2,7 +2,7 @@ title: mcp --- -The `nitro mcp` commands manage MCP feature collections. The Model Context Protocol (MCP) lets AI assistants and other clients discover and invoke capabilities exposed by your API. An MCP feature collection bundles a versioned set of prompt and tool definitions that Nitro serves to MCP clients on a given stage. +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. @@ -118,7 +118,7 @@ nitro mcp publish \ # `nitro mcp validate` -Validate a new MCP feature collection version against a stage without publishing it. Use this in CI to catch breaking changes before a deploy job runs. +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 \ @@ -164,21 +164,6 @@ nitro mcp list --api-id "" | `--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. | -## Examples - -List collections for an API: - -```shell -nitro mcp list --api-id "" -``` - -Page through collections in JSON mode: - -```shell -nitro mcp list --api-id "" --output json -nitro mcp list --api-id "" --output json --cursor "" -``` - # `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. @@ -198,17 +183,3 @@ nitro mcp delete "" | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | - -## Examples - -Delete with confirmation: - -```shell -nitro mcp delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro mcp delete "" --force -``` diff --git a/website/src/docs/nitro/cli/mock.md b/website/src/docs/nitro/cli/mock.md deleted file mode 100644 index 6c9ef711c96..00000000000 --- a/website/src/docs/nitro/cli/mock.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: mock ---- - -The `nitro mock` commands manage mock schemas. A mock schema is a hosted GraphQL endpoint that proxies a downstream service and overlays a schema extension on top of it, useful for prototyping clients against fields that do not yet exist in the real service or for stubbing parts of an API in tests. - -A mock schema is attached to an API and is defined by three pieces: the base `--schema` (the SDL of the downstream service), the `--extension` (additional types and fields layered on top), and the `--url` of the downstream service that real fields are forwarded to. - -All `mock` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](/docs/nitro/cli/global-options)). - -# `nitro mock create` - -Create a new mock schema under an API. - -```shell -nitro mock create \ - --api-id "" \ - --name "" \ - --schema \ - --extension \ - --url "" -``` - -## Options - -| Option | Env | Description | -| ------------------------- | ----------------------------- | ---------------------------------------------------------------------------------- | -| `--api-id ` | `NITRO_API_ID` | ID of the API to attach the mock schema to. | -| `--extension ` | `NITRO_SCHEMA_EXTENSION_FILE` | Path to the GraphQL file with the schema extension. Required. | -| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the base schema. Required. | -| `--url ` | `NITRO_DOWNSTREAM_URL` | URL of the downstream GraphQL service that real fields are forwarded to. Required. | -| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | Display name of the mock schema. Required. | - -## Examples - -Create a mock schema for a downstream service: - -```shell -nitro mock create \ - --api-id "" \ - --name "" \ - --schema ./schema.graphqls \ - --extension ./extension.graphql \ - --url "https://example.com/graphql" -``` - -# `nitro mock list` - -List all mock schemas in an API. Results are paginated, use the returned cursor to fetch the next page. - -```shell -nitro mock 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. | - -## Examples - -List mock schemas for an API: - -```shell -nitro mock list --api-id "" -``` - -Page through all mock schemas in JSON mode: - -```shell -nitro mock list --api-id "" --output json -nitro mock list --api-id "" --output json --cursor "" -``` - -# `nitro mock update` - -Update an existing mock schema. Every option is optional, only the fields you pass are changed. - -```shell -nitro mock update "" \ - --schema \ - --extension -``` - -## Arguments - -| Argument | Description | -| -------- | ------------------------------------------ | -| `` | ID of the mock schema to update. Required. | - -## Options - -| Option | Env | Description | -| ------------------------- | ----------------------------- | ------------------------------------------------------- | -| `--extension ` | `NITRO_SCHEMA_EXTENSION_FILE` | Path to the GraphQL file with the new schema extension. | -| `--schema ` | `NITRO_SCHEMA_FILE` | Path to the GraphQL file with the new base schema. | -| `--url ` | `NITRO_DOWNSTREAM_URL` | New URL of the downstream GraphQL service. | -| `--name ` | `NITRO_MOCK_SCHEMA_NAME` | New display name of the mock schema. | - -## Examples - -Replace the schema and extension files: - -```shell -nitro mock update "" \ - --schema ./schema.graphqls \ - --extension ./extension.graphql -``` - -Rename a mock schema: - -```shell -nitro mock update "" --name "" -``` - -Repoint a mock schema at a different downstream URL: - -```shell -nitro mock update "" --url "" -``` diff --git a/website/src/docs/nitro/cli/openapi.md b/website/src/docs/nitro/cli/openapi.md index 02cf369b787..5f0b1cd3529 100644 --- a/website/src/docs/nitro/cli/openapi.md +++ b/website/src/docs/nitro/cli/openapi.md @@ -2,9 +2,9 @@ title: openapi --- -The `nitro openapi` commands manage OpenAPI collections. An OpenAPI collection registers one or more OpenAPI documents with Nitro and tracks their versions across stages, so consumers always pick up the spec that matches the stage they target. +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 OpenAPI documents, optionally `validate` that version against a stage, then `publish` it. +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. @@ -115,7 +115,7 @@ nitro openapi publish \ # `nitro openapi validate` -Validate a new OpenAPI collection version against a stage without publishing it. Use this in CI to catch breaking changes before a deploy job runs. +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 \ @@ -158,21 +158,6 @@ nitro openapi list --api-id "" | `--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. | -## Examples - -List collections for an API: - -```shell -nitro openapi list --api-id "" -``` - -Page through collections in JSON mode: - -```shell -nitro openapi list --api-id "" --output json -nitro openapi list --api-id "" --output json --cursor "" -``` - # `nitro openapi delete` Delete an OpenAPI collection by its ID. Once deleted, the collection and all its versions are no longer accessible. @@ -192,17 +177,3 @@ nitro openapi delete "" | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | - -## Examples - -Delete with confirmation: - -```shell -nitro openapi delete "" -``` - -Delete in a script (no prompt): - -```shell -nitro openapi delete "" --force -``` diff --git a/website/src/docs/nitro/cli/pat.md b/website/src/docs/nitro/cli/pat.md index ec5f317a22a..205b09e9f96 100644 --- a/website/src/docs/nitro/cli/pat.md +++ b/website/src/docs/nitro/cli/pat.md @@ -4,6 +4,8 @@ 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. @@ -69,21 +71,6 @@ nitro pat list | ------------------- | -------------- | -------------------------------------------------------------------- | | `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | -## Examples - -List your tokens: - -```shell -nitro pat list -``` - -Page through tokens in JSON mode: - -```shell -nitro pat list --output json -nitro pat list --output json --cursor "" -``` - # `nitro pat revoke` Revoke a personal access token by its ID. Once revoked, any client using the token loses access immediately. @@ -103,19 +90,3 @@ nitro pat revoke "" | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `--force` | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with `--output json`. | - -## Examples - -Revoke with confirmation: - -```shell -nitro pat revoke "" -``` - -Revoke in a script (no prompt): - -```shell -nitro pat revoke "" --force -``` - -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. diff --git a/website/src/docs/nitro/cli/schema.md b/website/src/docs/nitro/cli/schema.md index a5f64b62873..0809c4d0f90 100644 --- a/website/src/docs/nitro/cli/schema.md +++ b/website/src/docs/nitro/cli/schema.md @@ -2,10 +2,12 @@ title: schema --- -The `nitro schema` commands manage the GraphQL schema (SDL) of an API. A schema version is uploaded with a `--tag` (for example `v1` or a Git commit SHA) and can then be validated against, or published to, a stage (for example `dev`, `staging`, `production`). +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` @@ -29,27 +31,18 @@ nitro schema upload \ ## Examples -Upload a schema version tagged with a Git commit: +Upload a schema version: ```shell nitro schema upload \ --api-id "" \ - --tag "$(git rev-parse HEAD)" \ + --tag "v1" \ --schema-file ./schema.graphqls ``` -Upload using environment variables (useful in CI): - -```shell -export NITRO_API_ID="" -export NITRO_TAG="v1" -export NITRO_SCHEMA_FILE="./schema.graphqls" -nitro schema upload -``` - # `nitro schema publish` -Publish a previously uploaded schema version to a stage. By default the publish fails if the version introduces breaking changes. Use `--force` to override, or `--wait-for-approval` to pause until a reviewer approves the change in the Nitro UI. +Publish a previously uploaded schema version to a stage. The version is identified by its tag. ```shell nitro schema publish \ @@ -60,50 +53,38 @@ nitro schema publish \ ## Options -| 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. | -| `--force` | | Skip confirmation prompts and publish even when the version contains breaking changes. | -| `--wait-for-approval` | `NITRO_WAIT_FOR_APPROVAL` | Wait for a reviewer to approve the deployment in Nitro before completing. | - -`--force` and `--wait-for-approval` are mutually exclusive. +| 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 a previously uploaded version to `dev`: +Publish to `dev`: ```shell nitro schema publish \ --api-id "" \ - --tag "" \ + --tag "v1" \ --stage "dev" ``` -Publish to `production` and wait for manual approval: +Publish to a gated stage and wait for approval: ```shell nitro schema publish \ --api-id "" \ - --tag "" \ + --tag "v1" \ --stage "production" \ --wait-for-approval ``` -Force-publish a version with known breaking changes: - -```shell -nitro schema publish \ - --api-id "" \ - --tag "" \ - --stage "dev" \ - --force -``` - # `nitro schema validate` -Validate a schema file against a stage without publishing it. The server returns the list of breaking, dangerous, and safe changes, plus any operations from registered clients that would break. +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 \ @@ -122,7 +103,7 @@ nitro schema validate \ ## Examples -Validate against a `dev` stage in a pull request check: +Validate against the `dev` stage: ```shell nitro schema validate \ diff --git a/website/src/docs/nitro/cli/session.md b/website/src/docs/nitro/cli/session.md index b0a53e5a20b..2fad1e55b08 100644 --- a/website/src/docs/nitro/cli/session.md +++ b/website/src/docs/nitro/cli/session.md @@ -20,12 +20,6 @@ nitro login | -------- | ------------------------------------------------------------------------------- | | `` | URL of the Nitro backend. Only needed for self-hosted or dedicated deployments. | -## Options - -| Option | Env | Description | -| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `--cloud-url ` | `NITRO_CLOUD_URL` | URL of the Nitro backend. Only needed for self-hosted or dedicated deployments. Defaults to `identity.chillicream.com`. | - ## Examples Log in against the default Nitro Cloud: @@ -40,12 +34,6 @@ Log in against a self-hosted or dedicated deployment using the positional argume nitro login "" ``` -Log in against a self-hosted or dedicated deployment using the option: - -```shell -nitro login --cloud-url "" -``` - # `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`. @@ -54,45 +42,21 @@ The `nitro logout` command logs you out and removes the locally stored session i nitro logout ``` -## Examples - -Log out of the current session: - -```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. -If no session exists, the command exits with an error and instructs you to run `nitro login`. - The `status` command requires authentication. Run `nitro login` first or pass `--api-key`. ```shell nitro status ``` -## Examples - -Show the current session: - -```shell -nitro status -``` - # `nitro launch` -The `nitro launch` command opens the Nitro web UI in your default browser. It's a convenience shortcut, useful for jumping from the terminal into the UI to create a workspace, browse APIs, or inspect telemetry. - -```shell -nitro launch -``` - -## Examples +The `nitro launch` command opens the Nitro web UI in your default browser. -Open the Nitro web UI: +When you're signed in to the default Nitro Cloud (or not signed in at all), it opens [https://nitro.chillicream.com](https://nitro.chillicream.com). When you're signed in to a self-hosted or dedicated deployment, it opens `/ui` derived from the API URL of your active session. ```shell nitro launch diff --git a/website/src/docs/nitro/cli/stage.md b/website/src/docs/nitro/cli/stage.md index 60167705fb3..089ef8af0aa 100644 --- a/website/src/docs/nitro/cli/stage.md +++ b/website/src/docs/nitro/cli/stage.md @@ -2,9 +2,9 @@ title: stage --- -The `nitro stage` commands manage the stages of an API. Stages live inside an [environment](/docs/nitro/cli/environment) and represent deployment targets (for example `dev`, `staging`, `production`) that schemas, clients, and fusion configurations are published to. +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`) define the promotion order between stages. +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)). @@ -63,20 +63,6 @@ nitro stage list --api-id "" | ------------------- | -------------- | ------------------------ | | `--api-id ` | `NITRO_API_ID` | ID of the API. Required. | -## Examples - -List stages for an API: - -```shell -nitro stage list --api-id "" -``` - -Get just the stage names in a script: - -```shell -nitro stage list --api-id "" --output json | jq -r '.values[].name' -``` - # `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. @@ -94,20 +80,3 @@ nitro stage delete \ | `--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`. | - -## Examples - -Delete a stage with confirmation: - -```shell -nitro stage delete --stage "" --api-id "" -``` - -Delete a stage in a script (no prompt): - -```shell -nitro stage delete \ - --stage "" \ - --api-id "" \ - --force -``` diff --git a/website/src/docs/nitro/cli/workspace.md b/website/src/docs/nitro/cli/workspace.md index b30f7096435..27dc02b086b 100644 --- a/website/src/docs/nitro/cli/workspace.md +++ b/website/src/docs/nitro/cli/workspace.md @@ -2,7 +2,7 @@ title: workspace --- -The `nitro workspace` commands manage workspaces. A workspace is the top-level container in Nitro, every API, environment, member, and API key belongs to exactly one 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. @@ -10,7 +10,7 @@ All `workspace` commands require authentication. Run `nitro login` first or pass # `nitro workspace create` -Create a new workspace. In interactive mode the CLI also asks whether to make the new workspace your default. +Create a new workspace. ```shell nitro workspace create --name "" @@ -18,27 +18,13 @@ nitro workspace create --name "" ## Options -| Option | Env | 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. | +| 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. -## Examples - -Create a workspace and set it as the default: - -```shell -nitro workspace create --name "" --default -``` - -Create a workspace without changing the default: - -```shell -nitro workspace create --name "" --default false -``` - # `nitro workspace list` List the workspaces you have access to. Results are paginated, use the returned cursor to fetch the next page. @@ -53,21 +39,6 @@ nitro workspace list | ------------------- | -------------- | -------------------------------------------------------------------- | | `--cursor ` | `NITRO_CURSOR` | Pagination cursor to resume from. Useful for non-interactive paging. | -## Examples - -List workspaces: - -```shell -nitro workspace list -``` - -Page through workspaces in JSON mode: - -```shell -nitro workspace list --output json -nitro workspace list --output json --cursor "" -``` - # `nitro workspace show` Show the details of a workspace by its ID. @@ -82,31 +53,9 @@ nitro workspace show "" | -------- | -------------------------------------- | | `` | ID of the workspace to show. Required. | -## Examples - -Show a workspace: - -```shell -nitro workspace show "" -``` - -Read just the name in a script: - -```shell -nitro workspace show "" --output json | jq -r '.name' -``` - # `nitro workspace current` -Show the name of the currently selected workspace. Exits with an error if no workspace is selected. - -```shell -nitro workspace current -``` - -## Examples - -Print the current workspace: +Show the name of the currently selected workspace. ```shell nitro workspace current @@ -125,17 +74,3 @@ nitro workspace set-default | Option | Env | Description | | ------------------------------- | -------------------- | ---------------------------------------------------------------------------- | | `--workspace-id ` | `NITRO_WORKSPACE_ID` | ID of the workspace to set as the default. Required in non-interactive mode. | - -## Examples - -Pick a workspace interactively: - -```shell -nitro workspace set-default -``` - -Set a specific workspace as the default: - -```shell -nitro workspace set-default --workspace-id "" -``` From b4e8e68d7a6ba83bc98e36cf226d63f59479c8f0 Mon Sep 17 00:00:00 2001 From: Tobias Tengler <45513122+tobias-tengler@users.noreply.github.com> Date: Wed, 6 May 2026 16:08:44 +0200 Subject: [PATCH 4/5] Update session.md --- website/src/docs/nitro/cli/session.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/src/docs/nitro/cli/session.md b/website/src/docs/nitro/cli/session.md index 2fad1e55b08..22c2265c9c2 100644 --- a/website/src/docs/nitro/cli/session.md +++ b/website/src/docs/nitro/cli/session.md @@ -56,8 +56,6 @@ nitro status The `nitro launch` command opens the Nitro web UI in your default browser. -When you're signed in to the default Nitro Cloud (or not signed in at all), it opens [https://nitro.chillicream.com](https://nitro.chillicream.com). When you're signed in to a self-hosted or dedicated deployment, it opens `/ui` derived from the API URL of your active session. - ```shell nitro launch ``` From 27f16999f3bafcf33e0888d9453e554800dfc191 Mon Sep 17 00:00:00 2001 From: tobias-tengler <45513122+tobias-tengler@users.noreply.github.com> Date: Wed, 6 May 2026 16:33:56 +0200 Subject: [PATCH 5/5] Address Copilot feedback --- .../Commands/Launch/LaunchCommand.cs | 2 +- website/src/docs/docs.json | 58 ------------------- website/src/docs/nitro/cli/environment.md | 4 +- website/src/docs/nitro/cli/fusion.md | 6 +- website/src/docs/nitro/cli/installation.md | 2 +- website/src/docs/nitro/cli/openapi.md | 22 +++---- 6 files changed, 16 insertions(+), 78 deletions(-) diff --git a/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs b/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs index f08bae806bf..ffe26b931dd 100644 --- a/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs +++ b/src/Nitro/CommandLine/src/CommandLine/Commands/Launch/LaunchCommand.cs @@ -34,7 +34,7 @@ private static Task ExecuteAsync( var url = ResolveUrl(sessionService.Session); browser.Open(url); - console.OkLine($"[link={url}]Nitro[/] is launched!"); + console.OkLine($"[link={url.EscapeMarkup()}]Nitro[/] is launched!"); return Task.FromResult(ExitCodes.Success); } diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index 5a4f288ea0c..de83b3a1324 100644 --- a/website/src/docs/docs.json +++ b/website/src/docs/docs.json @@ -186,72 +186,14 @@ "path": "openapi", "title": "openapi" }, - { - "path": "mock", - "title": "mock" - }, - { - "path": "environment", - "title": "environment" - }, - { - "path": "stage", - "title": "stage" - }, - { - "path": "workspace", - "title": "workspace" - } - ] - }, - { - "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": "fusion-configuration", - "title": "fusion-configuration" - }, { "path": "workspace", "title": "workspace" diff --git a/website/src/docs/nitro/cli/environment.md b/website/src/docs/nitro/cli/environment.md index 575e1edc4f4..bf891c47682 100644 --- a/website/src/docs/nitro/cli/environment.md +++ b/website/src/docs/nitro/cli/environment.md @@ -2,9 +2,7 @@ title: environment --- - - -The `nitro environment` commands manage environments. An environment is a workspace-level grouping that holds named [stages](/docs/nitro/cli/stage) (for example `dev`, `staging`, `production`) and is shared across the APIs in the workspace. +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)). diff --git a/website/src/docs/nitro/cli/fusion.md b/website/src/docs/nitro/cli/fusion.md index 86417ff3f0b..6060d2609f7 100644 --- a/website/src/docs/nitro/cli/fusion.md +++ b/website/src/docs/nitro/cli/fusion.md @@ -39,16 +39,14 @@ nitro fusion upload \ # `nitro fusion publish` - - -Publish a Fusion configuration to a stage. This is the one-shot command that runs validation, requests a deployment slot, and commits the new configuration in sequence. +Publish a Fusion configuration to a stage. ```shell nitro fusion publish \ --api-id "" \ --stage "" \ --tag "" \ - --archive "" + --source-schema products ``` ## Options diff --git a/website/src/docs/nitro/cli/installation.md b/website/src/docs/nitro/cli/installation.md index c32120d247c..e9081b61197 100644 --- a/website/src/docs/nitro/cli/installation.md +++ b/website/src/docs/nitro/cli/installation.md @@ -27,7 +27,7 @@ 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`. Pin the version with `@latest` so each run pulls the newest release: +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 diff --git a/website/src/docs/nitro/cli/openapi.md b/website/src/docs/nitro/cli/openapi.md index 5f0b1cd3529..9b025a1f962 100644 --- a/website/src/docs/nitro/cli/openapi.md +++ b/website/src/docs/nitro/cli/openapi.md @@ -43,7 +43,7 @@ nitro openapi create --name "" --api-id "" # `nitro openapi upload` -Upload a new version of an OpenAPI collection. OpenAPI documents are picked up via glob patterns. +Upload a new version of an OpenAPI collection. ```shell nitro openapi upload \ @@ -54,11 +54,11 @@ nitro openapi upload \ ## 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 the OpenAPI document files. Required. | +| 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 @@ -126,11 +126,11 @@ nitro openapi validate \ ## 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 the OpenAPI document files. Required. | +| 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