fmcli

A flexible, module-driven CLI framework. Define your own modules (JSON or TypeScript) and run them as first-class subcommands — no forking, no boilerplate.

Install

npm install -g @xingchuan-qxc/fmcli

Quick start

# Set your API host
fmcli config api-host set <url>

# Log in
fmcli login

# See available commands (built-in + your modules)
fmcli --help

Modules

fmcli discovers modules from ~/.fmcli/modules/ at startup. Each module is a self-contained .ts or .json file that registers one or more CLI subcommands.

TypeScript module

// ~/.fmcli/modules/hello/hello.ts
export default {
  command: "hello",
  description: "Say hello",
  register(cmd, ctx) {
    cmd.option("--name <name>", "Who to greet", "world");
    cmd.action((opts) => {
      console.log(`Hello, ${opts.name}!`);
    });
  },
};

JSON module

{
  "command": "my-query",
  "description": "Run a custom query",
  "sql": "SELECT COUNT(*) AS total FROM my_table WHERE place_id = :placeId",
  "params": {
    "placeId": { "source": "context", "field": "warehouseId" }
  }
}

Module directories

fmcli config dirs              # show module directories
fmcli config dirs add <path>   # add a directory
fmcli config dirs remove <path>
fmcli config modules           # list all registered modules

Version-based conflict resolution

When multiple directories contain a module with the same command name, the highest version wins. Same version — later directory wins.

Syncing modules

Back up and share modules via OSS:

fmcli sync push              # upload your modules
fmcli sync pull              # download your modules (cross-machine restore)
fmcli sync pull --user bob   # pull a teammate's modules
fmcli sync ls                # list remote modules

Commands

All commands are discoverable via --help:

fmcli --help
fmcli login --help
fmcli config --help
fmcli sync --help

Built-in commands

| Command | Description | |---------|-------------| | login | OAuth login (opens browser) | | login status | Show current login status | | login logout | Revoke token and log out | | config | Manage configuration | | sync | Sync modules to/from OSS | | update | Self-upgrade to latest version |

Configuration

Configuration is stored at ~/.fmcli/config.json:

fmcli config api-host set <url>    # set API host
fmcli config api-host show         # show current API host
fmcli config dirs                  # manage module directories

License

MIT