{"id":13454199,"url":"https://github.com/drew-y/cliffy","last_synced_at":"2025-04-12T20:47:22.993Z","repository":{"id":28879582,"uuid":"119562469","full_name":"drew-y/cliffy","owner":"drew-y","description":"NodeJS Framework for Interactive CLIs","archived":false,"fork":false,"pushed_at":"2024-06-16T15:11:48.000Z","size":223,"stargazers_count":362,"open_issues_count":7,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T20:46:49.224Z","etag":null,"topics":["cli","command","command-line","node","nodejs","repl","typescript","vorpal"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drew-y.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-30T16:25:33.000Z","updated_at":"2025-04-09T20:43:21.000Z","dependencies_parsed_at":"2024-10-28T21:46:09.162Z","dependency_job_id":null,"html_url":"https://github.com/drew-y/cliffy","commit_stats":{"total_commits":158,"total_committers":10,"mean_commits":15.8,"dds":"0.49367088607594933","last_synced_commit":"ce1c375c11fa1fb207308e659a4a4332d754db9f"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drew-y%2Fcliffy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drew-y%2Fcliffy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drew-y%2Fcliffy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drew-y%2Fcliffy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drew-y","download_url":"https://codeload.github.com/drew-y/cliffy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631718,"owners_count":21136559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command","command-line","node","nodejs","repl","typescript","vorpal"],"created_at":"2024-07-31T08:00:51.786Z","updated_at":"2025-04-12T20:47:22.959Z","avatar_url":"https://github.com/drew-y.png","language":"TypeScript","funding_links":[],"categories":["Packages","Repository","包","目录","TypeScript","cli","Command-line utilities","typescript"],"sub_categories":["Command-line utilities","Command-line Utilities","命令行工具","命令行实用工具"],"readme":"# Cliffy - A Framework For Interactive CLIs\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"500\" src=\"https://raw.githubusercontent.com/drew-y/cliffy/0b6a3939fe2c4455ad13c3745f9606c96d1a8cc3/demo.svg?sanitize=true\"\u003e\n\u003c/p\u003e\n\nCliffy is a simple, powerful utility for making interactive command line interfaces.\n\nCliffy is run as a REPL. This allows you to accept multiple commands\nwith one running node process. Cliffy is NOT an argv parser.\n\n**Features**:\n- REPL Style interface\n- Simple API\n- Can parse negative numbers\n- Typed parameters\n- Git Style Sub-Commands\n- Optional parameters  (New in v2)\n- Rest parameters (New in v2)\n- Options\n- Auto generated help\n- Typescript Support\n\n**Gotchas**:\n- Options are specified with an `@` symbol. Not `-` or `--`.\nThis is what allows Cliffy to parse negatives.\n- Requires node v6+\n\n## Quickstart\n\n**Installation**:\n\n```bash\nnpm i cliffy # --save if using npm \u003c v5\n```\n\n**Usage**\n\n```typescript\nimport { CLI } from \"cliffy\";\n\nconst cli = new CLI()\n    .setDelimiter(\"--\u003e\")\n    .addCommand(\"run\", {\n        description: \"Run somewhere\",\n        options: [{ label: \"quickly\", description: \"Run quickly\" }],\n        parameters: [\"destination\"],\n        action: (params, options) =\u003e {\n            if (options.quickly) {\n                console.log(`I ran to ${params.destination} quickly`)\n                return;\n            }\n\n            console.log(`I ran to ${params.destination}`)\n        },\n        subcommands: {\n            to: {\n                description: \"Run to a destination\",\n                parameters: [\"destination\"],\n                action: params =\u003e console.log(`I ran to ${params.destination}`)\n            },\n            from: {\n                description: \"Run from a destination\",\n                parameters: [\"location\"],\n                action: params =\u003e console.log(`I ran from ${params.location}`)\n            }\n        }\n    })\n    .show();\n```\n\nResult:\n\n```bash\n--\u003e run to nevada\nI ran to nevada\n--\u003e help\n\nAvailable commands:\n\n    run [options]  \u003cdestination\u003e    Run somewhere\n\n--\u003e help run\n\nRun somewhere\n\nUsage:\n\n    run [options] \u003cdestination\u003e\n\nOptions:\n\n   @quickly                          Run quickly\n\nSub-Commands:\n\n    to [options] \u003cdestination\u003e       Run to a destination\n    from [options] \u003cdestination\u003e     Run from a destination\n```\n\n## Quoted parameters\n\nParameters may be quoted using either ' (single) or \" (double) quotes. For example the command could be\n\n```\nsay \"Hello World\" 'Lovely Weather'\n```\n\nThis would give two parameters of `Hello World` and `Lovely Weather`.  When inside the quoted parameter, the other type of quotes can be used. This lets JSON be entered for example.\n\n```\nsay '{\"text\": \"This is the weather\"}'\n```\n\nWill give a parameter of the string, `{\"text\": \"This is the weather\"}` that can then be parsed as JSON.\n\n## Autogenerated Help Menu\n\nCliffy automatically generates a help menu for each command.\n\nTo get an overview of all the commands simply type:\n\n```\nhelp\n```\n\nTo get help with a specific command, type help followed by the command.\n\n```\nhelp ls\n```\n\nThis works with subcommands as well\n\n```\nhelp git pull\n```\n\n## Build instructions\n\n1. Clone this repo\n2. CD into the repo\n3. `npm install`\n4. `npm run build`\n\n## API\n\n### `new CLI()`\n\nInterface:\n```typescript\nclass CLI {\n    constructor(opts: {\n        input?: NodeJS.ReadableStream,\n        output?: NodeJS.WritableStream,\n         /** Set to true to prevent cliffy from displaying help text after entering a blank line. Defaults to false */\n        quietBlank?: boolean\n    } = {})\n}\n```\n\nUsage:\n\n```typescript\nconst cli = new CLI(opts)\n```\n\n### `cli.addCommand(name: string, command: Command): this`\n\nRegister a command\n\nTakes a name and a command object.\n\nThe command name is what the user will enter to execute the command.\n\nThe command interface is defined as follows:\n\n```typescript\ninterface Command {\n    /**\n     * The action to perform when its command is called.\n     *\n     * parameters is a key value store. Where the key is the parameter label,\n     * and its value is the value entered by the user.\n     *\n     * options is a key value store. Key being the option, value being true if the user\n     * specified the option, false otherwise.\n     */\n    action(parameters: any, options: { [key: string]: boolean }): void | Promise\u003cvoid\u003e;\n\n    /** Optional description for documentation */\n    description?: string;\n\n    /** Aliases the command can be accessed from */\n    aliases?: string[];\n\n    /**\n     * An array of options available to the user.\n     * The user specifies an option with an @ symbol i.e. @force\n     */\n    options?: (Option | string)[];\n\n    /**\n     * All the parameters available to the user.\n     * See the parameters interface.\n     *\n     * If a string is passed it is assumed to be string parameter\n     */\n    parameters?: (Parameter | string)[];\n\n    /** Sub commands of the command. Follows the same interface as Command */\n    subcommands?: Commands;\n}\n\nexport interface Parameter {\n    label: string;\n\n    /** The type to convert the provided value to. Can be a custom converter. */\n    type?: \"boolean\" | \"number\" | \"string\" | ((val: string) =\u003e any);\n\n    /** The parameter is optional */\n    optional?: boolean;\n\n    /**\n     * The parameter is a rest parameter.\n     *\n     * If true, the user can pass an indefinite amount of arguments\n     * that are put in an array set in this parameter.\n     **/\n    rest?: boolean;\n\n    /** Optional description for the help menu */\n    description?: string;\n}\n\nexport interface Option {\n    label: string;\n    description?: string;\n}\n```\n\nExample Usage:\n\n```typescript\ncli.addCommand(\"run\", {\n    description: \"Run somewhere\",\n    options: [{ option: \"fast\", description: \"Run fast\" }],\n    parameters: [{ label: \"destination\" }],\n    action: (params, options) =\u003e {\n        if (options.fast) return console.log(`I ran to ${params.destination} quickly`);\n        console.log(`I ran to ${params.destination}`);\n    },\n    subcommands: {\n        to: {\n            parameters: [{ label: \"destination\" }],\n            action: params =\u003e console.log(`I ran to ${params.destination}`),\n        }\n        from: {\n            parameters: [{ label: \"destination\" }],\n            action: params =\u003e console.log(`I ran to ${params.destination}),\n        }\n    }\n});\n```\n\n### `cli.addCommand(name: string, opts: Action): this`\n\nRegister a basic command.\n\nThis overload allows you to pass the action function directy.\nUseful for quick commands where parameters, options, and a\ndescription may not be needed.\n\nExample usage:\n\n```typescript\ncli.addCommand(\"speak\", () =\u003e sayHello(\"World\"));\n```\n\n### `cli.addCommands(commands: { [name: string]: Command | Action }): this`\n\nRegister multiple commands at once.\n\nExample usage:\n\n```typescript\ncli.addCommands({\n    run: {\n        action(params, options) {\n            console.log(\"Running\");\n        }\n    },\n\n    jog: {\n        action(params, options) {\n            console.log(\"Jogging\");\n        }\n    },\n\n    walk: {\n        action(params, options) {\n            console.log(\"Walking\");\n        }\n    }\n});\n```\n\n### `cli.setDelimiter(delimiter: string): this`\n\nSet the CLI delimiter\n\nDefaults to: `\"$\u003e\"`\n\n### `cli.setInfo(info: string): this`\n\nSet the CLI info.\n\nInfo is meant to give an overview of what the CLI does and how to use it.\nIf it is set it is shown directly under the CLI name.\n\nDefaults to: `none`\n\n### `cli.setName(name: string): this`\n\nSet the name of the CLI (Shown at the top of the help menu)\n\nDefaults to: `none`\n\n### `cli.setVersion(version: string): this`\n\nSet the CLI version. Shown beside the CLI name if set.\n\nDefaults to: `none`\n\n### `cli.show(): this`\n\nShow the CLI.\n\n### `cli.hide(): this`\n\nHide the cli.\n\n### `cli.showHelp(): this`\n\nShow the main help menu.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrew-y%2Fcliffy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrew-y%2Fcliffy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrew-y%2Fcliffy/lists"}