rdme

{ "commands": { "changelogs": { "aliases": [], "args": { "path": { "description": "Path to a local Markdown file or folder of Markdown files.", "name": "path", "required": true } }, "description": "Syncs Markdown files to the Changelog section of your ReadMe project. The path can either be a directory or a single Markdown file. The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter: https://docs.readme.com/main/docs/rdme#markdown-file-setup", "examples": [ { "description": "Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path input can also be individual Markdown files:", "command": "<%= config.bin %> <%= command.id %> [path] --version={project-version}" }, { "description": "This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode", "command": "<%= config.bin %> <%= command.id %> [path] --version={project-version} --dryRun" } ], "flags": { "github": { "description": "Create a new GitHub Actions workflow for this command.", "name": "github", "allowNo": false, "type": "boolean" }, "key": { "description": "An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v10#authentication", "name": "key", "required": true, "summary": "ReadMe project API key", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "dryRun": { "description": "Runs the command without creating/updating any changelogs in ReadMe. Useful for debugging.", "name": "dryRun", "allowNo": false, "type": "boolean" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "changelogs", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true, "summary": "Sync Markdown files to your ReadMe project as Changelog posts." }, "login": { "aliases": [], "args": {}, "description": "Login to a ReadMe project.", "flags": { "email": { "description": "Your email address", "name": "email", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "password": { "description": "Your password", "name": "password", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "otp": { "description": "Your one-time password (if you have two-factor authentication enabled)", "name": "otp", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "project": { "description": "The subdomain of the project you wish to log into", "name": "project", "hasDynamicHelp": false, "multiple": false, "type": "option" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "login", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true }, "logout": { "aliases": [], "args": {}, "description": "Logs the currently authenticated user out of ReadMe.", "flags": {}, "hasDynamicHelp": false, "hiddenAliases": [], "id": "logout", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true }, "openapi:convert": { "aliases": [], "args": { "spec": { "description": "A path to your API definition — either a local file path or a URL. If your working directory and all subdirectories contain a single OpenAPI file, you can omit the path.", "name": "spec" } }, "description": "Converts Swagger files and Postman collections to OpenAPI and bundles any external references. **Note**: All of our other OpenAPI commands already do this conversion automatically, but this command is available in case you need this functionality exclusively.", "examples": [ { "description": "By default, this command will display a comprehensive table of all OpenAPI and ReadMe features found in your API definition:", "command": "<%= config.bin %> <%= command.id %> [url-or-local-path-to-file]" }, { "description": "You can omit the file name and `rdme` will scan your working directory (and any subdirectories) for OpenAPI/Swagger files. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.", "command": "<%= config.bin %> <%= command.id %>" } ], "flags": { "out": { "description": "Output file path to write converted file to", "name": "out", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "title": { "description": "An override value for the `info.title` field in the API definition", "name": "title", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "workingDirectory": { "description": "Working directory (for usage with relative external references)", "name": "workingDirectory", "hasDynamicHelp": false, "multiple": false, "type": "option" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "openapi:convert", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true, "summary": "Converts an API definition to OpenAPI and bundles any external references." }, "openapi:inspect": { "aliases": [], "args": { "spec": { "description": "A path to your API definition — either a local file path or a URL. If your working directory and all subdirectories contain a single OpenAPI file, you can omit the path.", "name": "spec" } }, "description": "This command will perform a comprehensive analysis of your API definition to determine how it's utilizing aspects of the OpenAPI Specification (such as circular references, polymorphism, etc.) and any ReadMe-specific extensions you might be using.", "examples": [ { "description": "By default, this command will display a comprehensive table of all OpenAPI and ReadMe features found in your API definition:", "command": "<%= config.bin %> <%= command.id %> [url-or-local-path-to-file]" }, { "description": "You can omit the file name and `rdme` will scan your working directory (and any subdirectories) for OpenAPI/Swagger files. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.", "command": "<%= config.bin %> <%= command.id %>" }, { "description": "If you wish to automate this command, it contains a `--feature` flag so you can filter for one or several specific features. If you pass in one or more `--feature` flags, the command returns a `0` exit code if your definition contains all of the given features and a `1` exit code if your definition lacks any of the given features:", "command": "<%= config.bin %> <%= command.id %> [url-or-local-path-to-file] --feature circularRefs --feature polymorphism" } ], "flags": { "feature": { "description": "A specific OpenAPI or ReadMe feature you wish to see detailed information on (if it exists). If any features supplied do not exist within the API definition an exit(1) code will be returned alongside the report.", "name": "feature", "hasDynamicHelp": false, "multiple": true, "options": [ "additionalProperties", "callbacks", "circularRefs", "commonParameters", "discriminators", "links", "style", "polymorphism", "serverVariables", "webhooks", "xml", "readme" ], "type": "option" }, "workingDirectory": { "description": "Working directory (for usage with relative external references)", "name": "workingDirectory", "hasDynamicHelp": false, "multiple": false, "type": "option" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "openapi:inspect", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true, "summary": "Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage." }, "openapi:reduce": { "aliases": [], "args": { "spec": { "description": "A path to your API definition — either a local file path or a URL. If your working directory and all subdirectories contain a single OpenAPI file, you can omit the path.", "name": "spec" } }, "description": "Reduce your API definition down to a specific set of tags or paths, which can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain.", "examples": [ { "description": "By default, this command will ask you a couple questions about how you wish to reduce the file and then do so:", "command": "<%= config.bin %> <%= command.id %> [url-or-local-path-to-file]" }, { "description": "You can omit the file name and `rdme` will scan your working directory (and any subdirectories) for OpenAPI/Swagger files. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.", "command": "<%= config.bin %> <%= command.id %>" }, { "description": "If you wish to automate this command, you can pass in CLI arguments to bypass the prompts:", "command": "<%= config.bin %> <%= command.id %> petstore.json --path /pet/{id} --method get --method put --out petstore.reduced.json" } ], "flags": { "method": { "description": "Methods to reduce by (can only be used alongside the `path` option)", "name": "method", "hasDynamicHelp": false, "multiple": true, "type": "option" }, "out": { "description": "Output file path to write reduced file to", "name": "out", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "path": { "description": "Paths to reduce by", "name": "path", "hasDynamicHelp": false, "multiple": true, "type": "option" }, "tag": { "description": "Tags to reduce by", "name": "tag", "hasDynamicHelp": false, "multiple": true, "type": "option" }, "title": { "description": "An override value for the `info.title` field in the API definition", "name": "title", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "workingDirectory": { "description": "Working directory (for usage with relative external references)", "name": "workingDirectory", "hasDynamicHelp": false, "multiple": false, "type": "option" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "openapi:reduce", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true, "summary": "Reduce an OpenAPI definition into a smaller subset." }, "openapi:upload": { "aliases": [], "args": { "spec": { "description": "A path to your API definition — either a local file path or a URL. If your working directory and all subdirectories contain a single OpenAPI file, you can omit the path.", "name": "spec" } }, "description": "By default, the slug (i.e., the unique identifier for your API definition resource in ReadMe) will be inferred from the spec name and path. As long as you maintain these directory/file names and run `rdme` from the same location relative to your file, the inferred slug will be preserved and any updates you make to this file will be synced to the same resource in ReadMe.\n\nIf the spec is a local file, the inferred slug takes the relative path and slugifies it (e.g., the slug for `docs/api/petstore.json` will be `docs-api-petstore.json`).\n\nIf the spec is a URL, the inferred slug is the base file name from the URL (e.g., the slug for `https://example.com/docs/petstore.json` will be `petstore.json`).", "examples": [ { "description": "You can pass in a file name like so:", "command": "<%= config.bin %> <%= command.id %> --version=1.0.0 openapi.json" }, { "description": "You can also pass in a file in a subdirectory (we recommend always running the CLI from the root of your repository):", "command": "<%= config.bin %> <%= command.id %> --version=v1.0.0 example-directory/petstore.json" }, { "description": "You can also pass in a URL:", "command": "<%= config.bin %> <%= command.id %> --version=1.0.0 https://example.com/openapi.json" }, { "description": "If you specify your ReadMe project version in the `info.version` field in your OpenAPI definition, you can use that:", "command": "<%= config.bin %> <%= command.id %> --useSpecVersion https://example.com/openapi.json" } ], "flags": { "key": { "description": "An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v10#authentication", "name": "key", "required": true, "summary": "ReadMe project API key", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "slug": { "description": "Allows you to override the slug (i.e., the unique identifier for your API definition resource in ReadMe) that's inferred from the API definition's file/URL path.\n\nYou do not need to include a file extension (i.e., either `custom-slug.json` or `custom-slug` will work). If you do, it must match the file extension of the file you're uploading.", "name": "slug", "summary": "Override the slug (i.e., the unique identifier) for your API definition.", "hasDynamicHelp": false, "multiple": false, "type": "option" }, "useSpecVersion": { "description": "If included, use the version specified in the `info.version` field in your OpenAPI definition for your ReadMe project version. This flag is mutually exclusive with `--version`.", "exclusive": [ "version" ], "name": "useSpecVersion", "summary": "Use the OpenAPI `info.version` field for your ReadMe project version", "allowNo": false, "type": "boolean" }, "version": { "description": "Defaults to `stable` (i.e., your main project version). This flag is mutually exclusive with `--useSpecVersion`.", "name": "version", "summary": "ReadMe project version", "default": "stable", "hasDynamicHelp": false, "multiple": false, "type": "option" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "openapi:upload", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true, "summary": "Upload (or re-upload) your API definition to ReadMe." }, "openapi:validate": { "aliases": [], "args": { "spec": { "description": "A path to your API definition — either a local file path or a URL. If your working directory and all subdirectories contain a single OpenAPI file, you can omit the path.", "name": "spec" } }, "description": "Perform a local validation of your API definition (no ReadMe account required!), which can be useful when constructing or editing your API definition.", "examples": [ { "description": "This will validate the API definition at the given URL or path:", "command": "<%= config.bin %> <%= command.id %> [url-or-local-path-to-file]" }, { "description": "You can omit the file name and `rdme` will scan your working directory (and any subdirectories) for OpenAPI/Swagger files. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.", "command": "<%= config.bin %> <%= command.id %>" } ], "flags": { "github": { "description": "Create a new GitHub Actions workflow for this command.", "name": "github", "allowNo": false, "type": "boolean" }, "workingDirectory": { "description": "Working directory (for usage with relative external references)", "name": "workingDirectory", "hasDynamicHelp": false, "multiple": false, "type": "option" } }, "hasDynamicHelp": false, "hiddenAliases": [], "id": "openapi:validate", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true, "summary": "Validate your OpenAPI/Swagger definition." }, "whoami": { "aliases": [], "args": {}, "description": "Displays the current user and project authenticated with ReadMe.", "flags": {}, "hasDynamicHelp": false, "hiddenAliases": [], "id": "whoami", "pluginAlias": "rdme", "pluginName": "rdme", "pluginType": "core", "strict": true } }, "version": "10.1.1" }