"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", h3: "h3", li: "li", p: "p", ul: "ul", ..._provideComponents(), ...props.components }, {AccordionGroup, CodeBlock, CodeBlocks, Note, Tip, Warning} = _components; if (!AccordionGroup) _missingMdxReference("AccordionGroup", true); if (!CodeBlock) _missingMdxReference("CodeBlock", true); if (!CodeBlocks) _missingMdxReference("CodeBlocks", true); if (!Note) _missingMdxReference("Note", true); if (!Tip) _missingMdxReference("Tip", true); if (!Warning) _missingMdxReference("Warning", true); return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "Explore documentation for popular Fern CLI commands." }), "\n", _jsx(AccordionGroup, { items: [{ "title": "fern check", "id": "fern-check", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern check" }), " to validate your API definition and Fern configuration: ", _jsx(_components.code, { children: "fern.config.json" }), ", ", _jsx(_components.code, { children: "generators.yml" }), ", and ", _jsx(_components.code, { children: "docs.yml" }), "."] }), _jsx(_components.p, { children: "When successfully executed, this command will not produce any output." }), _jsx(CodeBlocks, { items: [{ "code": "fern check [--api ] [--warnings]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h3, { id: "api", children: "api" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--api " }), " to specify which API you’d like to check."] }), _jsx(CodeBlock, { code: "fern check --api public-api\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "warnings", children: "warnings" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--warnings" }), " to log warnings in addition to errors."] }), _jsx(CodeBlock, { code: "fern check --warnings\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h2, { id: "usage-in-a-github-action", children: "Usage in a GitHub Action" }), _jsx(CodeBlocks, { items: [{ "code": "name: Fern Validation Check\n\non:\npull_request:\nbranches: - main\n\njobs:\nvalidate-fern-api:\nname: Validate using Fern's linter\nruns-on: ubuntu-latest\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Set up Node.js\n uses: actions/setup-node@v2\n with:\n node-version: '14'\n\n - name: Install Fern\n run: npm install -g fern-api\n\n - name: Validate API with Fern\n run: fern check\n\n", "language": "yml", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 14, "title": ".github/workflows/fern-check.yml", "wordWrap": false }] })] }) }, { "title": "fern generate", "id": "fern-generate", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern generate" }), " to run the Fern compiler and create SDKs for your API."] }), _jsx(CodeBlocks, { items: [{ "code": "fern generate [--group ] [--api ] [--version ] [--local] [--keepDocker]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h3, { id: "group", children: "group" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--group " }), " to filter to a specific group within ", _jsx(_components.code, { children: "generators.yml" }), ". Required unless you have a ", _jsx(_components.code, { children: "default-group" }), " declared in ", _jsx(_components.code, { children: "generators.yml" }), "."] }), _jsx(CodeBlock, { code: "fern generate --group internal\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "api-1", children: "api" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--api " }), " to specify the API for SDK generation."] }), _jsx(CodeBlock, { code: "fern generate --api public-api\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "version", children: "version" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--version" }), " to specify a version for SDKs and documentation. Adherance to ", _jsx(_components.a, { href: "https://semver.org/", children: "semantic versioning" }), " is advised."] }), _jsx(CodeBlock, { code: "fern generate --version 2.11\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "local", children: "local" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--local" }), " to generate code locally by downloading the Docker Image and running it on your machine.\nNote that running Docker locally supports outputting files, and not publishing to package managers."] }), _jsx(CodeBlock, { code: "fern generate --local\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsxs(Warning, { children: [" ", _jsx(_components.a, { href: "https://www.docker.com/products/docker-desktop/", children: "Docker Desktop" }), " must be installed and running on your machine. "] }), _jsx(_components.h3, { id: "keepdocker", children: "keepDocker" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--keepDocker" }), " to keep the Docker container running after the generation is complete. This is useful for debugging."] }), _jsx(CodeBlock, { code: "fern generate --local --keepDocker\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsxs(Warning, { children: [" ", _jsx(_components.a, { href: "https://www.docker.com/products/docker-desktop/", children: "Docker Desktop" }), " must be installed and running on your machine. "] })] }) }, { "title": "fern generate --docs", "id": "fern-generate---docs", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern generate --docs" }), " to create a documentation site for your API."] }), _jsx(CodeBlocks, { items: [{ "code": "fern generate --docs [instance ] [--preview]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h3, { id: "instance", children: "instance" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--instance" }), " to specify which instance URL in your ", _jsx(_components.code, { children: "docs.yml" }), " to generate documentation for."] }), _jsx(CodeBlock, { code: "fern generate --docs --instance your-organization.docs.buildwithfern.com\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "preview", children: "preview" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--preview" }), " to preview updates to your documentation before publishing changes to your production site."] }), _jsx(CodeBlock, { code: "fern generate --docs --preview\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false })] }) }, { "title": "fern docs dev", "id": "fern-docs-dev", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern docs dev" }), " to run a local development server to preview your docs."] }), _jsx(CodeBlocks, { items: [{ "code": "fern docs dev [--port ]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h3, { id: "port", children: "port" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--port " }), " to specify the port the docs preview will be run on."] }), _jsx(CodeBlock, { code: "fern docs dev --port 57908\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false })] }) }, { "title": "fern upgrade", "id": "fern-upgrade", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern upgrade" }), " will upgrade your compiler version in ", _jsx(_components.code, { children: "fern.config.json" }), " to the\nlatest version. It will also upgrade generators in ", _jsx(_components.code, { children: "generators.yml" }), " to their minimum-compatible versions."] }), _jsx(CodeBlocks, { items: [{ "code": "fern upgrade [--rc]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h3, { id: "rc", children: "rc" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--rc" }), " to upgrade to the compiler’s latest release candidate. Using a release candidate is not recommended for production use."] }), _jsx(CodeBlock, { code: "fern upgrade --rc\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false })] }) }, { "title": "fern init", "id": "fern-init", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern init" }), " to initialize a new Fern workspace in the current folder. By default, you’ll see the IMDb API example."] }), _jsx(CodeBlocks, { items: [{ "code": "fern init [--docs]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.p, { children: "This will create the following folder structure in your project:" }), _jsx(CodeBlock, { code: "fern/\n├─ fern.config.json # root-level configuration\n├─ generators.yml # generators you're using\n└─ definition/\n ├─ api.yml # API-level configuration\n └─ imdb.yml # endpoints, types, and errors\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "docs", children: "docs" }), _jsxs(_components.p, { children: ["By adding ", _jsx(_components.code, { children: "--docs" }), ", you’ll also get a sample documentation website for your API with an API Reference section."] }), _jsx(CodeBlock, { code: "fern init --docs\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.p, { children: "The file added will contain:" }), _jsx(CodeBlocks, { items: [{ "code": "instances:\n - url: https://your-organization.docs.buildwithfern.com\ntitle: Your Organization | Documentation\nnavigation:\n - api: API Reference\ncolors:\naccentPrimary: '#ffffff'\nbackground: '#000000'\n", "language": "yaml", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "wordWrap": false, "title": "docs.yaml" }] }), _jsxs(_components.p, { children: ["To publish the API docs, run ", _jsx(_components.a, { href: "/learn/cli-api/cli-reference/commands#fern-generate---docs", children: _jsx(_components.code, { children: "fern generate --docs" }) }), "."] }), _jsx(Tip, { children: _jsxs(_components.p, { children: ["For more information on getting started, check out our ", _jsx(_components.a, { href: "/learn/docs/getting-started/quickstart", children: "Quickstart Guide" })] }) })] }) }, { "title": "fern login", "id": "fern-login", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern login" }), " to login to the Fern CLI via GitHub. Logging in allows you\njoin GitHub organizations, gain permissions, and contribute to projects."] }), _jsx(CodeBlocks, { items: [{ "code": "fern login [--device code]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h3, { id: "device-code", children: "device-code" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--device-code" }), " to login via device code authorization."] }), _jsx(CodeBlock, { code: "fern login --device-code\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(Note, { children: _jsxs(_components.p, { children: ["To enable CI/CD, use ", _jsx(_components.a, { href: "/cli-api/cli-reference/commands#fern-token", children: _jsx(_components.code, { children: "fern token" }) }), "."] }) })] }) }, { "title": "fern token", "id": "fern-token", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern token " }), "to generate a ", _jsx(_components.code, { children: "FERN_TOKEN" }), " specific to your organization defined\nin ", _jsx(_components.code, { children: "fern.config.json" }), ". Use the token to authenticate with the API in CI. Tokens do not expire."] }), _jsx(CodeBlocks, { items: [{ "code": "fern token\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsx(_components.h2, { id: "github-actions", children: "GitHub Actions" }), _jsxs(_components.p, { children: ["If using GitHub Actions as your CI, add the ", _jsx(_components.code, { children: "FERN_TOKEN" }), " as a ", _jsx(_components.a, { href: "https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository", children: "GitHub Action secret" }), " in your Fern configuration repo.\nYou can then reference the secret in your CI:"] }), _jsx(CodeBlock, { code: "- name: Generate and Publish Documentation with Fern\n env:\n FERN_TOKEN: ${{ secrets.FERN_TOKEN }}\n run: fern generate --docs\n", language: "yaml", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsxs(_components.p, { children: ["See ", _jsx(_components.a, { href: "https://github.com/fern-api/fern/blob/main/.github/workflows/publish-docs.yml", children: "the full example on GitHub" }), "."] })] }) }, { "title": "fern write-definition", "id": "fern-write-definition", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern write-definition" }), " to convert your OpenAPI Specification into a Fern Definition.\nYou must have a ", _jsx(_components.code, { children: "fern/openapi/" }), " folder that contains an OpenAPI Specification file in ", _jsx(_components.code, { children: ".json" }), " or ", _jsx(_components.code, { children: ".yaml" }), " format."] }), _jsx(CodeBlocks, { items: [{ "code": "fern write-definition [--api ]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsxs(_components.p, { children: ["When run, this command creates a new folder within ", _jsx(_components.code, { children: "fern/" }), " called ", _jsx(_components.code, { children: ".definition/" }), "."] }), _jsx(CodeBlock, { code: "fern/\n├─ fern.config.json\n├─ generators.yml\n└─ openapi/\n └─ openapi.json\n └─ .definition/ # <--- your Fern Definition\n └─ api.yml\n └─ __package__.yml\n", language: "bash", highlightLines: [6, 7, 8], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(Warning, { children: _jsxs(_components.p, { children: ["If you do not see the ", _jsx(_components.code, { children: ".definition/" }), " folder, use the appropriate command or configuration to view hidden folders (", _jsx(_components.code, { children: "ls -a" }), " in ", _jsx(_components.code, { children: "bash" }), " and ", _jsx(_components.code, { children: "zsh" }), ")."] }) }), _jsxs(_components.p, { children: ["If your ", _jsx(_components.code, { children: "fern/" }), " folder contains both an ", _jsx(_components.code, { children: "openapi/" }), " and a ", _jsx(_components.code, { children: "definition/" }), " folder, Fern defaults to reading your OpenAPI Specification. To use your Fern Definition as input, you must:"] }), _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Rename the ", _jsx(_components.code, { children: ".definition/" }), " folder to ", _jsx(_components.code, { children: "definition/" }), "."] }), "\n", _jsxs(_components.li, { children: ["Remove or rename the ", _jsx(_components.code, { children: "openapi/" }), " folder. For example, you can rename it to ", _jsx(_components.code, { children: ".openapi/" }), "."] }), "\n"] }), _jsx(_components.h3, { id: "api-2", children: "api" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--api" }), " to specify the API to write the definition for if you have multiple defined in your ", _jsx(_components.code, { children: "fern/apis/" }), " folder."] }), _jsx(CodeBlock, { code: "fern write-definition --api public-api\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false })] }) }, { "title": "fern write-overrides", "id": "fern-write-overrides", "children": _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "fern write-overrides" }), " to generate a basic OpenAPI overrides file. An overrides file allows for\nreversible revisions to the API specification, including adding request and response examples for\ncode snippets in Fern Docs."] }), _jsx(CodeBlocks, { items: [{ "code": "fern write-overrides [--api ] [--exclude-models]\n", "language": "bash", "highlightLines": [], "highlightStyle": "highlight", "maxLines": 20, "title": "terminal", "wordWrap": false }] }), _jsxs(_components.p, { children: ["When run, this command creates a new file within ", _jsx(_components.code, { children: "fern/openapi/" }), " called ", _jsx(_components.code, { children: "openapi-overrides.yml" }), "."] }), _jsx(CodeBlock, { code: "fern/\n├─ fern.config.json\n├─ generators.yml\n└─ openapi/\n └─ openapi-overrides.yaml # <--- your overrides file\n └─ openapi.json\n", language: "bash", highlightLines: [5], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "api-3", children: "api" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--api" }), " to specify the API to run the command on if multiple are defined."] }), _jsx(CodeBlock, { code: "fern write-overrides --api public-api\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false }), _jsx(_components.h3, { id: "exclude-models", children: "exclude-models" }), _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "--exclude-models" }), " to stub the models while generating the initial overrides (in addition to the endpoints)."] }), _jsx(CodeBlock, { code: "fern write-overrides --exclude-models\n", language: "bash", highlightLines: [], highlightStyle: "highlight", maxLines: 20, wordWrap: false })] }) }], toc: true })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }