# Cordis Command-Line Options: Understanding the Minimal CLI Design

> Discover Cordis command-line options. Cordis uses a minimal CLI, loading all configuration exclusively from cordis.yml, simplifying your workflow.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: api-reference
- Published: 2026-09-13

---

**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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`.

```bash

# 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`](https://github.com/cordiverse/cordis/blob/main/cordis.yml).

## Configuring Cordis via cordis.yml

Since you cannot pass command-line options to Cordis directly, you modify **[`cordis.yml`](https://github.com/cordiverse/cordis/blob/main/cordis.yml)** to control application behavior. The loader plugin (referenced in [`packages/loader/src/config/utils.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/config/utils.ts)) processes this file to instantiate plugins with specific settings.

```yaml

# 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`](https://github.com/cordiverse/cordis/blob/main/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.

```bash

# 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`](https://github.com/cordiverse/cordis/blob/main/cordis.yml) file read by the loader plugin.
- **Entry point is minimal** – The [`packages/core/bin.js`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/packages/core/bin.js) entry point hardcodes the expectation for [`cordis.yml`](https://github.com/cordiverse/cordis/blob/main/cordis.yml) in the current working directory. To use a different configuration file, you must either rename it to [`cordis.yml`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/cordis.yml) file.