Cordis Command-Line Options: Understanding the Minimal CLI Design

Cordis intentionally provides no custom command-line flags; instead, the cordis executable initializes a Context, sets the base URL to the current working directory, loads the built-in loader plugin, and reads all configuration exclusively from a cordis.yml file.

The cordiverse/cordis repository follows a distinctive philosophy for command-line interfaces. Unlike typical Node.js applications that parse arguments using libraries like commander or yargs, Cordis maintains an intentionally minimal CLI that delegates all configuration management to its YAML-based loader system.

How the Core CLI Works

The primary entry point for Cordis is located in packages/core/bin.js. This script performs a fixed sequence of operations without parsing custom arguments.

When you run the cordis command, the executable performs three critical actions:

1. Creates a Context – Initializes the Cordis dependency injection container.
2. Sets the base URL – Assigns ctx.baseUrl to the current working directory (process.cwd()).
3. Loads the configuration – Activates the @cordisjs/plugin-loader plugin, which then creates a loader instance for @cordisjs/plugin-include using the cordis.yml file found in the base directory.

Because the script does not invoke argument-parsing libraries, Cordis does not support bespoke switches like --port, --config, or --env. The implementation relies entirely on Node.js’s native argument handling for basic flags like --help or --version.

# Run Cordis (looks for cordis.yml in the current directory)

cordis

# Node.js native flags still work (but show Node.js help, not Cordis-specific)

cordis --help

Why Cordis Omits Traditional CLI Flags

The absence of custom command-line options for Cordis is an intentional architectural decision. The framework treats the CLI as a thin bootstrap layer rather than a configuration interface.

By avoiding argument parsers, Cordis ensures that all configuration lives in version-controlled YAML files rather than ephemeral command-line strings. This approach makes deployments reproducible and eliminates environment-specific startup scripts. Any behavior you might typically configure via flags—such as plugin options, logging levels, or feature toggles—must be declared explicitly in cordis.yml.

Configuring Cordis via cordis.yml

Since you cannot pass command-line options to Cordis directly, you modify cordis.yml to control application behavior. The loader plugin (referenced in packages/loader/src/config/utils.ts) processes this file to instantiate plugins with specific settings.

# Example cordis.yml configuration

plugins:
  - name: my-plugin
    options:
      foo: bar
      port: 3000
  - name: another-plugin
    options:
      debug: true

When the CLI launches, the loader reads this configuration and injects the specified options into each plugin’s Context. This file-based approach replaces the need for environment-specific CLI flags.

The Scaffold CLI (create-cordis)

The ecosystem includes a scaffolding tool implemented in packages/create/src/bin.ts. Like the core CLI, this tool accepts no additional flags. It simply invokes a scaffold helper using the package name and version, generating a new Cordis project structure without interactive prompts or command-line switches.

# Creates a new Cordis project (no flags accepted)

npm create cordis my-project

Summary

• Cordis provides no custom CLI flags – The executable intentionally avoids argument parsing libraries like commander or yargs.
• Configuration is YAML-based – All runtime behavior is controlled through the cordis.yml file read by the loader plugin.
• Entry point is minimal – The packages/core/bin.js script only creates a Context, sets the base URL, and loads the plugin system.
• Node.js native flags still function – Standard arguments like --help and --version work via Node.js itself, but return generic Node.js output rather than Cordis-specific documentation.

Frequently Asked Questions

Does Cordis support a --config flag to specify an alternative configuration file?

No. The packages/core/bin.js entry point hardcodes the expectation for cordis.yml in the current working directory. To use a different configuration file, you must either rename it to cordis.yml or launch Cordis from a directory where that specific file exists.

How do I change the base URL if Cordis has no --base-url CLI option?

The base URL is automatically set to process.cwd() inside packages/core/bin.js via ctx.baseUrl. If you need to change the base directory, invoke the cordis command from that directory rather than passing a flag. The CLI uses the execution context as the configuration root.

What Node.js arguments work with the Cordis command?

Since Cordis does not intercept process.argv, standard Node.js flags like --help, --version, --inspect, and --experimental-modules pass through to the Node.js runtime. However, these provide Node.js-level functionality rather than Cordis-specific behavior.

Can I add custom CLI flags to my Cordis application?

Cordis does not expose a hook for CLI argument parsing in its core bin.js. To implement custom flags, you would need to create a custom entry point that parses arguments before initializing the Cordis Context, or handle configuration exclusively through environment variables referenced in your cordis.yml file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}