CLI Reference
Polen provides several CLI commands to help you develop and deploy your GraphQL developer portal.
Common Options
Most Polen commands that operate on projects accept these common options:
--project <path>
,-p
- Path to the project directory (default: current working directory)
Commands
polen create
Create a new Polen project from a template.
npx polen create [name] [options]
Arguments:
[name]
- The name of your project (optional, defaults to a random name)
Options:
--path <path>
,-p
- Directory to create the project in--example <name>
,-e
- Example template to use (default:hive
)--version <version>
,-v
- Polen version to install (default: latest)--link
,-l
- Link to a local Polen installation instead of installing from npm
Examples:
# Create with default settings
npx polen create
# Create with a specific name
npx polen create my-api-docs
# Create in a specific directory
npx polen create my-docs --path ./projects/docs
# Use a specific Polen version
npx polen create --version 1.2.3
# Use local Polen installation (for development)
npx polen create my-docs --link
polen build
Build your developer portal for production deployment.
npx polen build [options]
Options:
--project <path>
,-p
- Path to the project directory (default: current working directory)--architecture <type>
,-a
- Build architecture:ssg
(default) orssr
--base <path>
,-b
- Base path for deployment (e.g.,/my-project/
)--port <number>
- Default port for the SSR application (default: 3000)--debug
,-d
- Enable debug mode (default: false)
polen dev
Start the development server with hot reloading.
npx polen dev [options]
Options:
--project <path>
,-p
- Path to the project directory (default: current working directory)--base <path>
,-b
- Base path for development (e.g.,/my-project/
)--port <number>
- Port for the development server (default: 3000)--debug
,-d
- Enable debug mode
polen open
Instantly view any GraphQL schema with Polen's schema explorer. You can provide a schema in three ways: from a well-known API, via introspection, or from an SDL file.
npx polen open [options]
Options (mutually exclusive):
--name <name>
,-n
- Name of a well-known schema:github
orhive
--introspect <url>
,-i
- Get schema via GraphQL introspection from a URL--sdl <path>
,-s
- Get schema from an SDL file (local path or HTTP URL)
Additional options:
--introspection-headers <json>
- Headers for introspection requests (JSON format)
Examples:
# Open a well-known schema
npx polen open --name github
# Introspect a GraphQL endpoint
npx polen open --introspect https://api.graphql-hive.com/graphql
# Introspect with authentication (using environment variable)
npx polen open --introspect https://api.github.com/graphql \
--introspection-headers "{\"Authorization\": \"Bearer $GITHUB_TOKEN\"}"
# Load from a local SDL file
npx polen open --sdl ./schema.graphql
# Load from a remote SDL file
npx polen open --sdl https://docs.github.com/public/fpt/schema.docs.graphql
polen config create
Create a Polen configuration file.
npx polen config create [options]
Options:
--project <path>
,-p
- Path to the project directory (default: current working directory)
This command:
- Creates a
polen.config.ts
file in the project directory - Does nothing if the file already exists
- Scaffolds a basic TypeScript configuration with type-safe imports
The generated file contains:
import { Polen } from 'polen'
export default Polen.defineConfig({
// Your configuration options
})
polen static rebase
Update the base path of a built Polen site without rebuilding.
npx polen static rebase <source> <newBasePath> [options]
Arguments:
<source>
- Path to the Polen build directory to rebase<newBasePath>
- New base path for the build (e.g.,/new-path/
)
Options:
--target <path>
,-t
- Target directory for copy mode. If not provided, mutates in place
Examples:
# Mutate in place (default)
npx polen static rebase ./build /new-base/
# Copy to new location
npx polen static rebase ./build /staging/ --target ./build-staging
Learn more in the Static Rebase documentation.
Global Options
All commands support these global options:
--help
- Show help for the command--version
- Show Polen version