Commands

Environments

Each environment is a file in the project root named fusion.<env>.json.

New projects start with three environments:

File	Environment
`fusion.dev.json`	`dev` (default)
`fusion.stage.json`	`stage`
`fusion.prod.json`	`prod`

Add more by creating another file — for example fusion.test.json becomes the test environment. No extra registration is required.

Environment file shape

{
  "env": "dev",
  "config": {
    "debug": true,
    "host": "127.0.0.1",
    "port": 8080,
    "secret_key": "change-me"
  },
  "commands": {
    "run": "python main.py"
  }
}

config — application settings read by core/settings (and by Fusion Framework at runtime)
commands — shell commands you run with fusion command <name>

Swagger (optional)

New projects also include a swagger block under config (enabled in dev, typically off in stage / prod). Edit it to control the docs UI, OpenAPI info, and auth schemes:

{
  "env": "dev",
  "config": {
    "host": "127.0.0.1",
    "port": 8080,
    "swagger": {
      "enabled": true,
      "path": "/swagger",
      "title": "Fusion API Docs",
      "info": {
        "title": "Fusion API",
        "version": "1.0.0",
        "description": "API documentation generated by fusion-framework"
      },
      "servers": [{ "url": "/", "description": "Current host" }],
      "auth": {
        "persistAuthorization": true,
        "schemes": {
          "BearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "JWT"
          },
          "ApiKeyAuth": {
            "type": "apiKey",
            "in": "header",
            "name": "X-API-Key"
          }
        },
        "global": [],
        "oauth": {
          "clientId": "",
          "appName": "Fusion API",
          "usePkceWithAuthorizationCodeGrant": true
        }
      },
      "navbar": {
        "enabled": true,
        "showUrlInput": true
      },
      "ui": {
        "deepLinking": true,
        "docExpansion": "list",
        "filter": true,
        "tryItOutEnabled": true
      }
    }
  },
  "commands": {
    "run": "python main.py"
  }
}

Useful keys:

Key	Purpose
`swagger.enabled`	Turn Swagger UI on or off
`swagger.path`	UI path (default `/swagger`)
`auth.schemes` / `auth.global`	OpenAPI security definitions
`auth.oauth`	Passed to Swagger UI `initOAuth`
`navbar.enabled`	Show the Swagger top bar
`swagger.ui`	Maps to Swagger UI configuration

Running commands

Commands are whatever you declare under commands. Run one by name:

fusion command run
fusion command run:dev
fusion command run --stage
fusion command run:stage
fusion command run --prod
fusion command run --env test

Example: start the sample API

After fusion init and pip install fusion-framework:

fusion command run:dev

That runs python main.py with FUSION_ENV=dev. Using the default config you get:

API: http://127.0.0.1:8080
Swagger UI: http://127.0.0.1:8080/swagger

Fusion builds the OpenAPI/Swagger docs for you from your route modules (including the starter products module). Use Swagger UI to call endpoints, inspect schemas, and try auth — no extra docs setup required.

Without a flag or :env suffix, the environment is taken from FUSION_ENV if set, otherwise dev.

List the commands declared for an environment:

fusion command --stage

Fusion runs the shell string from the project root (sh -c on Linux/macOS, cmd /C on Windows) and sets FUSION_ENV so settings load the matching file. The process exit code is forwarded — useful for scripts and CI.

Custom commands

Add any entry you need:

{
  "env": "stage",
  "config": { "port": 1010 },
  "commands": {
    "run": "docker compose up",
    "stop": "docker compose down"
  }
}

fusion command stop --stage

Custom environments

Create fusion.test.json, then:

fusion command run --test
# or
fusion command run --env test

Install the framework package

After scaffolding, install the language runtime package for the project:

pip install fusion-framework

Language guides: TypeScript / Node.js and C#.

Commands

On this page