{"id":19589774,"url":"https://github.com/supercharge/console-io","last_synced_at":"2025-04-27T12:33:05.214Z","repository":{"id":48392407,"uuid":"362094850","full_name":"supercharge/console-io","owner":"supercharge","description":"Opinionated UI kit for CLI inputs and outputs.","archived":false,"fork":false,"pushed_at":"2023-07-25T08:14:53.000Z","size":1034,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-05T00:26:05.343Z","etag":null,"topics":["cli","console","supercharge","uikit"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supercharge.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2021-04-27T11:55:29.000Z","updated_at":"2024-12-27T21:27:36.000Z","dependencies_parsed_at":"2024-11-11T08:35:24.055Z","dependency_job_id":null,"html_url":"https://github.com/supercharge/console-io","commit_stats":{"total_commits":102,"total_committers":2,"mean_commits":51.0,"dds":0.303921568627451,"last_synced_commit":"b424ec11556bdcbab92649a480475ae38cb1ad4d"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercharge%2Fconsole-io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercharge%2Fconsole-io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercharge%2Fconsole-io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supercharge%2Fconsole-io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supercharge","download_url":"https://codeload.github.com/supercharge/console-io/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251138934,"owners_count":21541976,"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","console","supercharge","uikit"],"created_at":"2024-11-11T08:20:44.478Z","updated_at":"2025-04-27T12:33:04.787Z","avatar_url":"https://github.com/supercharge.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\r\n  \u003ca href=\"https://superchargejs.com\"\u003e\r\n    \u003cimg width=\"471\" style=\"max-width:100%;\" src=\"https://superchargejs.com/images/supercharge-text.svg\" /\u003e\r\n  \u003c/a\u003e\r\n  \u003cbr/\u003e\r\n  \u003cbr/\u003e\r\n  \u003cp\u003e\r\n    \u003ch3\u003eConsole IO\u003c/h3\u003e\r\n  \u003c/p\u003e\r\n  \u003cp\u003e\r\n    Opinionated UI kit for CLI inputs and outputs.\r\n  \u003c/p\u003e\r\n  \u003cbr/\u003e\r\n  \u003cp\u003e\r\n    \u003ca href=\"#installation\"\u003e\u003cstrong\u003eInstallation\u003c/strong\u003e\u003c/a\u003e ·\r\n    \u003ca href=\"#table-of-contents\"\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/a\u003e\r\n    \u003ca href=\"#usage\"\u003e\u003cstrong\u003eUsage\u003c/strong\u003e\u003c/a\u003e\r\n  \u003c/p\u003e\r\n  \u003cbr/\u003e\r\n  \u003cbr/\u003e\r\n  \u003cp\u003e\r\n    \u003ca href=\"https://www.npmjs.com/package/@supercharge/console-io\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@supercharge/console-io.svg\" alt=\"Latest Version\"\u003e\u003c/a\u003e\r\n    \u003ca href=\"https://www.npmjs.com/package/@supercharge/console-io\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@supercharge/console-io.svg\" alt=\"Monthly downloads\"\u003e\u003c/a\u003e\r\n  \u003c/p\u003e\r\n  \u003cp\u003e\r\n    \u003cem\u003eFollow \u003ca href=\"http://twitter.com/marcuspoehls\"\u003e@marcuspoehls\u003c/a\u003e and \u003ca href=\"http://twitter.com/superchargejs\"\u003e@superchargejs\u003c/a\u003e for updates!\u003c/em\u003e\r\n  \u003c/p\u003e\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n![Supercharge: Console IO Logging](https://github.com/supercharge/console-io/blob/main/assets/logging-preview.png)\r\n\r\n\r\n## Introduction\r\nThe `@supercharge/console-io` package is a CLI UI kit. It provides an opinionated styling for console outputs and allows you to easily retrieve user retrieve input from the terminal.\r\n\r\n\r\n## Installation\r\n\r\n```\r\nnpm i @supercharge/console-io\r\n```\r\n\r\n\r\n## Table of Contents\r\n\r\n- [Usage](#usage)\r\n- [Input](#input)\r\n  - [`input.ask(message, builder?)`](#inputaskmessage-builder)\r\n  - [`input.confirm(message, builder?)`](#inputconfirmmessage-builder)\r\n  - [`input.password(message, builder?)`](#inputpasswordmessage-builder)\r\n  - [`input.secure(message)`](#inputsecuremessage)\r\n  - [`input.choice(message, builder)`](#inputchoicemessage-builder)\r\n- [Output](#output)\r\n  - [Logging](#logging)\r\n    - [`output.log(message)`](#outputlogmessage)\r\n    - [`output.logError(message)`](#outputlogerrormessage)\r\n    - [`output.blankLine()`](#outputblankline)\r\n    - [`output.info(message)`](#outputinfomessage)\r\n    - [`output.warn(message)`](#outputwarnmessage)\r\n    - [`output.debug(message)`](#outputdebugmessage)\r\n    - [`output.error(message|Error)`](#outputerrormessage--error)\r\n    - [`output.success(labelOrMessage, message?)`](#outputsuccesslabelormessage-message)\r\n    - [`output.hint(labelOrMessage, message?)`](#outputhintlabelormessage-message)\r\n    - [`output.fail(labelOrMessage, message?)`](#outputfaillabelormessage-message)\r\n  - [Tags](#tags)\r\n    - [`output.tag(label).success(message)`](#outputtaglabelsuccessmessage)\r\n    - [`output.tag(label).info(message, reason?)`](#outputtaglabelinfomessage-reason)\r\n    - [`output.tag(label).failed(message, reason?)`](#outputtaglabelfailedmessage-reason)\r\n  - [Spinner](#spinner)\r\n    - [`output.spinner(message)`](#outputspinnermessage)\r\n    - [`output.withSpinner(message, callback)`](#outputwithspinnermessage-callback)\r\n\r\n\r\n## Usage\r\nUsing `@supercharge/console-io` is pretty straightforward.\r\n\r\n```js\r\nconst { ConsoleInput, ConsoleOutput } = require('@supercharge/console-io')\r\n\r\nasync function askForAndPrintTheName () {\r\n  const input = new ConsoleInput()\r\n  const output = new ConsoleOutput()\r\n\r\n  // asking the for input\r\n  const name = await io.ask('What’s your name')\r\n\r\n  // printing output to the terminal\r\n  output.success('Hello', name)\r\n}\r\n```\r\n\r\n\r\n## Input\r\nThe package exports a `ConsoleInput` class. This class allows you to prompt users for input on the command line.\r\n\r\nFor example, you may ask the user for text input or to confirm/decline a given question.\r\n\r\nHere’s how you create a console input instance called `input`. The following console input examples refer to this `input` instance when calling the individual methods.\r\n\r\n```js\r\nconst { ConsoleInput } = require('@supercharge/console-io')\r\n\r\nconst input = new ConsoleInput()\r\n```\r\n\r\n\r\n#### input.ask(message, builder?)\r\nPrompts the user for text input:\r\n\r\n```js\r\nconst name = await input.ask('What’s your name')\r\n```\r\n\r\nThe `ask` method accepts an optional builder callback as the second argument. This builder callback allows you to refine the question. Refining the question can be defining a default value or transforming the answer:\r\n\r\n```js\r\nconst name = await input.ask('What’s your name', builder =\u003e {\r\n  builder\r\n    .defaultValue('Marcus')\r\n    .transform(answer =\u003e String(answer).toUpperCase())\r\n})\r\n\r\n// `name` when pressing enter using the default value: MARCUS\r\n// `name` when providing 'test' as the value: TEST\r\n```\r\n\r\n\r\n#### input.confirm(message, builder?)\r\nPrompts the user for a confirmation returning `true` or `false`:\r\n\r\n```js\r\nconst proceed = await input.confirm('This deletes all files. Proceed?')\r\n```\r\n\r\nThe `confirm` method accepts a builder callback as the second argument. This builder callback allows you to refine the question. Refining the question can be defining a default value or transforming the answer:\r\n\r\n```js\r\nconst proceed = await input.confirm('This deletes all files. Proceed?', builder =\u003e {\r\n  builder\r\n    .defaultValue(false)\r\n    .transform(answer =\u003e answer ? 1 : 0) // transforms `true` to `1` and `false` to `0`\r\n})\r\n\r\n// `proceed` when pressing enter using the default value: 0\r\n// `proceed` when selecting the truthy value: 1\r\n```\r\n\r\n\r\n#### input.password(message, builder?)\r\nPrompts the user for a password input. The typed input is masked with stars:\r\n\r\n```js\r\nconst password = await input.password('Provide your password')\r\n```\r\n\r\nThe `password` method accepts a builder callback as the second argument. This builder callback allows you to refine the password prompt: you can make the input visible, like the password prompts on Linux systems:\r\n\r\n```js\r\nconst password = await input.password('Provide your password (not visible when typing)', builder =\u003e {\r\n  builder\r\n    .invisible()\r\n    .transform(name =\u003e String(name).toLowerCase())\r\n})\r\n\r\n// `password` when typing \"Supercharge\": \"supercharge\"\r\n```\r\n\r\n\r\n#### input.secure(message)\r\nPrompts the user for a secure input which is not visible when the user types the input:\r\n\r\n```js\r\nconst secret = await input.secure('Provide your password')\r\n```\r\n\r\nThe `secure` method accepts is a shortcut to an invisible password prompts. It doesn’t show the input, not even masked with stars.\r\n\r\n\r\n#### input.choice(message, builder)\r\nPrompts the user to select from a list of choices. Use the `builder` in the callback function to create and configure the available choices:\r\n\r\n```js\r\nconst choice = await input.choice('Choose your favorite framework', builder =\u003e {\r\n  builder.add('Supercharge').withValue('supercharge')\r\n  builder.add('Express').withValue('express').disabled()\r\n})\r\n\r\n// `choice` when selecting \"Supercharge\": \"supercharge\"\r\n```\r\n\r\n\r\n## Output\r\nThe package exports a `ConsoleOutput` class. This class allows you to print expressive and colored messages to the terminal.\r\n\r\nFor example, you may use console output to create expressive and colored terminal messages.\r\n\r\nHere’s how you create a console output instance called `output`. The following console output examples refer to this `output` instance when calling the individual methods:\r\n\r\n```js\r\nconst { ConsoleOutput } = require('@supercharge/console-io')\r\n\r\nconst output = new ConsoleOutput()\r\n```\r\n\r\n### Logging\r\nThe console output exposes a handful methods. Here’s a preview how the console output looks like:\r\n\r\n![Supercharge: Console IO Output](https://github.com/supercharge/console-io/blob/main/assets/logging-all.png)\r\n\r\n\r\n#### output.log(message)\r\nPrints a log message to `stdout`. Works like `console.log` but uses the log renderer. Log renderers can be swapped for better testing:\r\n\r\n```js\r\noutput.log('Supercharge is sweet!')\r\n```\r\n\r\n\r\n#### output.logError(message)\r\nPrints a log message to `stderr`. Works like `console.error` but uses the log renderer. Log renderers can be swapped for better testing:\r\n\r\n```js\r\noutput.log('Supercharge is sweet!')\r\n```\r\n\r\n\r\n#### output.blankLine()\r\nPrints an empty line to the terminal. Useful to create whitespace:\r\n\r\n```js\r\noutput.blankLine()\r\n```\r\n\r\n\r\n#### output.info(message)\r\nPrints the given info `message` to the terminal. Info messages will be prefixed with an “INFO” tag on a cyan background:\r\n\r\n```js\r\noutput.info('info message')\r\n```\r\n\r\n\r\n#### output.warn(message)\r\nPrints the given warning `message` to the terminal. Warning messages will be prefixed with a “WARN” tag on a yellow background:\r\n\r\n```js\r\noutput.info('warning message')\r\n```\r\n\r\n\r\n#### output.debug(message)\r\nPrints the given debug `message` to the terminal. Debug messages will be prefixed with a “DEBUG” tag on a blue background:\r\n\r\n```js\r\noutput.debug('debug message')\r\n```\r\n\r\n\r\n#### output.error(message | Error)\r\nPrints the given error `message` or message from the `Error` instance to the terminal. Error messages will be prefixed with an “ERROR” tag on a red background:\r\n\r\n```js\r\noutput.debug('debug message')\r\n```\r\n\r\nWhen providing an `Error` instance, the stack trace will be printed dimmed below the error message.\r\n\r\n\r\n#### output.success(labelOrMessage, message?)\r\nPrints a success message to the terminal. When providing a single parameter to `.success(message)`, the text will be printed in green. You may provide the label and message parameters to create a success tag for the given `label` with the related `message`:\r\n\r\n```js\r\n// just a success message\r\noutput.success('Green-colored success message')\r\n\r\n// success message with label\r\noutput.success('SUCCESS', 'success message')\r\n```\r\n\r\n\r\n#### output.hint(labelOrMessage, message?)\r\nPrints a hint message to the terminal. When providing a single parameter to `.hint(message)`, the text will be printed in blue. You may provide the label and message parameters to create a hint tag for the given `label` with the related `message`:\r\n\r\n```js\r\n// just a hint message\r\noutput.hint('Blue-colored hint message')\r\n\r\n// hint message with label\r\noutput.hint('SKIPPED', 'hint message')\r\n```\r\n\r\n\r\n#### output.fail(labelOrMessage, message?)\r\nPrints a fail message to the terminal. When providing a single parameter to `.fail(message)`, the text will be printed in red. You may provide the label and message parameters to create a fail tag for the given `label` with the related `message`:\r\n\r\n```js\r\n// just a fail message\r\noutput.fail('Red-colored fail message')\r\n\r\n// fail message with label\r\noutput.fail('FAILED', 'fail message')\r\n```\r\n\r\n\r\n### Tags\r\nThe `ConsoleOutput` class provides a `.tag(label)` method creating a pending tag output. The pending tag must be completed with a given message. The tag message relates to one of the available states. The tag states define the colors. At this point, there are three tags availabe: `success`, `info`, `failed`.\r\n\r\n\r\n![Supercharge: Console IO Output](https://github.com/supercharge/console-io/blob/main/assets/tags.png)\r\n\r\n\r\n#### output.tag(label).success(message)\r\nPrints a success tag to the terminal. The tag `label` is printed with dark text on a green background. The `message` provides more context data:\r\n\r\n```js\r\noutput.tag(' FINISHED ').success('Database migrations')\r\n```\r\n\r\n\r\n#### output.tag(label).info(message, reason?)\r\nPrints an info tag to the terminal. The tag `label` is printed with dark text on a blue background. The `message` provides more context data:\r\n\r\n```js\r\noutput.tag(' IGNORED ').info('config/app.js file for this run')\r\noutput.tag(' SKIPPED ').info('Copying .env', 'File already exists.')\r\n```\r\n\r\n#### output.tag(label).failed(message, reason?)\r\nPrints a fail tag to the terminal. The tag `label` is printed with dark text on a red background. The `message` provides more context data:\r\n\r\n```js\r\noutput.tag(' FAILED ').failed('to copy .env file', 'File already exists.')\r\n```\r\n\r\n\r\n### Spinner\r\nA `ConsoleOutput` instance provides the `.spinner(message)` and `.withSpinner(message, callback)` methods creating and returning a loading spinner with the given `message`. You can process long-running tasks while showing the loading spinner. You must manually stop the when using the `.spinner(message)` method. Stopping and starting the spinner is handled for you when using the `.withSpinner(message, callback)` method.\r\n\r\n\r\n![Supercharge: Console IO Spinner](https://github.com/supercharge/console-io/blob/main/assets/spinner.gif)\r\n\r\n\r\n#### Spinner Interface\r\nYou can change the state (message) of a loading spinner by using one of the following three methods:\r\n\r\n- `spinner.update(message)`: update the previous spinner text to the given `message`\r\n- `spinner.done(message?)`: stop the spinner and mark it as “done”. Optionally update the spinner text to the given `message`\r\n- `spinner.fail(message?)`: stop the spinner and mark it as “failed”. Optionally update the spinner text to the given `message`\r\n\r\n\r\n#### output.spinner(message)\r\nCreates and returns a started loading spinner for the given `message`:\r\n\r\n```js\r\nconst spinner = output.spinner('Installing dependencies')\r\nawait installDependencies()\r\n\r\nspinner.update('Processing long-running task')\r\nawait processOtherLongRunningTask()\r\n\r\nspinner.stop('Setup complete')\r\n```\r\n\r\n\r\n#### output.withSpinner(message, callback)\r\nReturns a promise and runs the given `callback` action. The `callback` receives a started loading spinner instance. Using this method allows you to group actions of a long-running task into a callback function:\r\n\r\n```js\r\nconst result = await output.withSpinner('Installing dependencies', async spinner =\u003e {\r\n  await installDependencies()\r\n\r\n  spinner.update('Completing setup')\r\n  await completeSetup()\r\n\r\n  /**\r\n   * You can manually stop the spinner with a custom message. You can also skip\r\n   * stopping the spinner here if you’re fine using the previous message as\r\n   * the \"done\" message. Stopping the spinner is already handled for you.\r\n   */\r\n  spinner.stop('Setup complete')\r\n\r\n  /**\r\n   * You may return a value from this callback and use it later in your code.\r\n   */\r\n  return { done: true }\r\n})\r\n```\r\n\r\nYou must handle errors youself in case one of your methods inside the `callback` throws an error. A common approach is wrapping your code in a `try/catch` block and handling the error after catching it. Here’s an example on how you may handle errors:\r\n\r\n```js\r\ntry {\r\n  await output.withSpinner('A failing spinner', async () =\u003e {\r\n    throw new Error('Uff, failed!')\r\n  })\r\n} catch (error) {\r\n  output.error(error.message)\r\n}\r\n```\r\n\r\n\r\n## Contributing\r\nDo you miss a function? We very much appreciate your contribution! Please send in a pull request 😊\r\n\r\n1.  Create a fork\r\n2.  Create your feature branch: `git checkout -b my-feature`\r\n3.  Commit your changes: `git commit -am 'Add some feature'`\r\n4.  Push to the branch: `git push origin my-new-feature`\r\n5.  Submit a pull request 🚀\r\n\r\n\r\n## License\r\nMIT © [Supercharge](https://superchargejs.com)\r\n\r\n---\r\n\r\n\u003e [superchargejs.com](https://superchargejs.com) \u0026nbsp;\u0026middot;\u0026nbsp;\r\n\u003e GitHub [@supercharge](https://github.com/supercharge) \u0026nbsp;\u0026middot;\u0026nbsp;\r\n\u003e Twitter [@superchargejs](https://twitter.com/superchargejs)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupercharge%2Fconsole-io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupercharge%2Fconsole-io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupercharge%2Fconsole-io/lists"}