@xingchuan-qxc/fmcli 1.0.2

package/README.md

@@ -0,0 +1,115 @@
+# 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
+
+```bash
+npm install -g @xingchuan-qxc/fmcli
+```
+
+## Quick start
+
+```bash
+# 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
+
+```ts
+// ~/.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
+
+```json
+{
+  "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
+
+```bash
+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:
+
+```bash
+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`:
+
+```bash
+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`:
+
+```bash
+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