{"id":20792623,"url":"https://github.com/mkrl/ttty","last_synced_at":"2025-12-12T03:42:04.157Z","repository":{"id":38173384,"uuid":"152907344","full_name":"mkrl/ttty","owner":"mkrl","description":"A very simple, tiny \u0026 pure JS lightweight terminal \"emulator\"","archived":false,"fork":false,"pushed_at":"2024-09-24T18:15:02.000Z","size":325,"stargazers_count":65,"open_issues_count":3,"forks_count":11,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T23:34:58.022Z","etag":null,"topics":["browser","cli","command-line","console","javascript","terminal","typescript"],"latest_commit_sha":null,"homepage":"http://mkrl.xyz/ttty","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/mkrl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2018-10-13T19:30:44.000Z","updated_at":"2025-03-14T16:56:10.000Z","dependencies_parsed_at":"2024-12-16T15:41:39.780Z","dependency_job_id":"2b56f946-52d4-46ab-b64c-f982625853c6","html_url":"https://github.com/mkrl/ttty","commit_stats":null,"previous_names":["mkrl/plainterm.js"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrl%2Fttty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrl%2Fttty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrl%2Fttty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrl%2Fttty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkrl","download_url":"https://codeload.github.com/mkrl/ttty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250328107,"owners_count":21412561,"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":["browser","cli","command-line","console","javascript","terminal","typescript"],"created_at":"2024-11-17T15:53:05.505Z","updated_at":"2025-12-12T03:41:59.124Z","avatar_url":"https://github.com/mkrl.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\n# ttty\n\nA dead simple lightweight TypeScript terminal \"emulator\" that mimics terminal behaviour in browser.\n\nFeatures:\n\n - Tiny, dependency-free and built with modern JS\n - Easy-to-add custom commands\n - Events\n - Command history\n - Command arguments with validation\n - \"Foreground processes\" imitation\n\n\n## Usage\n\n### With module bundler\n\nAdd the latest release with:\n\n`npm install ttty`\nor\n`yarn add ttty`\n\nInitialize the terminal in a particular DOM element with:\n\n```js\nimport { initTerminal } from 'ttty'\n\n// ...\n\nconst terminal = initTerminal({ /* settings */ })\n```\n\n### In a browser directly\n\n```html\n\u003c!-- As a global JS file --\u003e\n\u003cscript src=\"https://unpkg.com/ttty/dist/ttty.iife.js\"\u003e\u003c/script\u003e\n```\n```js\nttty.initTerminal({ /* settings */ })\n```\n\nInitialize with parameters:\n\n```js\nconst settings = {\n    host: document.querySelector(\"#terminal\"),\n    prompt: \"user@ttty:~$ \",\n    commands: {\n        echo: {\n            name: \"echo\", \n            description: \"a test command with one echo arg\", \n            argDescriptions: [\"a string to be echoed in console\"],\n            func: ({ print }, argument) =\u003e { print(argument) } \n        },\n        test: {\n            name: \"test\", \n            description: \"a test command with no args\", \n            func: ({ print }) =\u003e { print(\"foo\") } \n        },\n        multiply: {\n            name: \"multiply\",\n            description: \"Multiply two numbers\",\n            argDescriptions: [\"number one\", \"number two\"],\n            func: ({ print }, one, two) =\u003e { print(Number(one) * Number(two)) }\n        }\n    }\n}\n\ninitTerminal(settings)\n```\n\n## Working with the terminal\n\n`help` - Display a list of all commands with descriptions\n\n`command` - Execute a command. Will display \"Usage: command [parameter 1 description] [parameter 2 description], etc.\", when it requires arguments but is called without them.\n\n## API\n\n### initTerminal\n\n| Method  | Description | Parameters |\n| ------------- | ------------- | ------------- |\n| `init(settings)`  | Initialize a terminal in a given DOM element | `settings` object. |\n\n### terminal\n\nAn object that's being passed to every command function \u0026 returned by `initTerminal`\n\n| Method                                             | Description                                                                                                                                                       | Parameters                                                                                                                                |\n|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|\n| `print(text, isCommand, scrollIntoView)`           | Prints a given text in the terminal (accepts raw HTML)                                                                                                            | `text` - String, `isCommand` - Boolean, optional, defaults to false. Count given string as a command (displays prompt \u0026 syntax highlight) |\n| `run(text)`                                        | Emulates a command execution in a terminal (acts the same way as a user would have typed and pressed Enter)                                                       | `text` - String                                                                                                                           |\n| `start()`                                          | Starts a \"foreground process\": user input is blocked and command prompt never appears.                                                                            |                                                                                                                                           |\n| `stop()`                                           | Stops \"foreground process\".                                                                                                                                       |                                                                                                                                           |\n| `type(text, speed, isCommand) =\u003e Promise\u003cboolean\u003e` | Prints a text with \"typing\" effect. Hides and blocks user input while typing. Resolves to either `true` or `false` depending on process interruption by the user. | `text` - String, text to be printed. `speed` - integer, miliseconds. The higher the number, the slower. `isCommand` - Boolean, optional, defaults to false. Count given string as a command (displays prompt \u0026 syntax highlight)                                  |\n| `setPrompt()`                                      | Set terminal prompt                                                                                                                                               | `newPrompt` - String                                                                                                                      |\n\n### settings object\n\n| Parameter  | Description | Default |\n| ------------- | ------------- | ------------- |\n| `host`: DOM element | A DOM element to initialize terminal in. |  |\n| `welcomeMessage`: string | A welcome message that is being printed on initialization |  |\n| `enableHelp`: boolean | Toggle default `help` command that lists all the available commands and their descriptions. | true |\n| `prompt`: string | Terminal prompt | '$: ' |\n| `historyLength`: number | A maximum amount of commands that can be stored in the terminal history | 50 |\n| `history`: string[] | A default value for terminal history (can be used to preserve history across sessions) | [] |\n| `commands`: object | `commands` object |  |\n\n### commands object\n\n| Parameter  | Description | \n| ------------- | ------------- | \n| `name`: string | Command name. | \n| `description`: string | Command description, used for the default `help` command (when enabled). | \n| `argDescriptions`: string array | Array of strings that describe command line arguments in order of appearance. | \n| `func`: function(terminal, ...arguments) | Function. Accepts an array of parameters in order of appearance (i.e. `function(terminal, one, two)` will correspond to two arguments passed as `command one two`) | \n\n\n\n## Events\n\n| Event  | Description \n| ------------- | ------------- |\n| `onInit`  | Terminal initialization |\n| `onCommand`  | Existing command executed |\n| `onCommand404`  | Non-existing command executed |\n| `onProcessStart`  | Process started |\n| `onProcessStop`  | Process stopped |\n| `onProcessInterrupt`  | Process interrupted with a keyboard |\n\nEvents are being dispatched by the DOM element passed on init, for example:\n\n```\nconst term = document.getElementById('terminal');\nterm.addEventListener('onCommand', e =\u003e console.log(\"known command executed!\"));\n```\n\n## Custom styling\n\nYou can customize the look defining custom CSS variables. If you have multiple instances, you can even have each instance in its' own style!\n\n| Variable  | Description\n| ------------- | ------------- |\n| `--terminal-bg-color`  | Background color |\n| `--terminal-fg-color`  | Text color |\n| `--terminal-font`  | Terminal font-family |\n| `--terminal-accent-color`  | Accent color |\n| `--terminal-error-color`  | Error color |\n\n## Browser compatibility\n\nttty is built and distributed with ES6 in mind (including the minified package). You can always transpile \u0026 bundle it targeting your browser set of choice.\n\nBrowsers that do not support CSS variables (IE \u003c 11) might not be able to make use of custom themes. In order to use ttty with older browsers please rebuild this with custom properties removed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkrl%2Fttty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkrl%2Fttty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkrl%2Fttty/lists"}