{"id":13529731,"url":"https://github.com/pvarentsov/iola","last_synced_at":"2025-06-22T10:36:27.081Z","repository":{"id":45030649,"uuid":"366321525","full_name":"pvarentsov/iola","owner":"pvarentsov","description":"🔄 iola: Command-line socket client with REST API.","archived":false,"fork":false,"pushed_at":"2023-10-12T21:28:39.000Z","size":16303,"stargazers_count":161,"open_issues_count":0,"forks_count":15,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-22T06:13:29.485Z","etag":null,"topics":["iola","socket-client","socketio-client","tcp-client","unix-socket-client","websocket-client"],"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/pvarentsov.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-05-11T09:09:18.000Z","updated_at":"2025-05-14T00:46:21.000Z","dependencies_parsed_at":"2024-01-03T04:13:49.231Z","dependency_job_id":"770a9695-02fc-44d0-84c2-114f5e459ead","html_url":"https://github.com/pvarentsov/iola","commit_stats":{"total_commits":501,"total_committers":2,"mean_commits":250.5,"dds":0.001996007984031989,"last_synced_commit":"66da5f7873ac6c617ed0d252dc8fb62f7dfddc7c"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/pvarentsov/iola","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvarentsov%2Fiola","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvarentsov%2Fiola/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvarentsov%2Fiola/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvarentsov%2Fiola/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pvarentsov","download_url":"https://codeload.github.com/pvarentsov/iola/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvarentsov%2Fiola/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261279967,"owners_count":23134898,"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":["iola","socket-client","socketio-client","tcp-client","unix-socket-client","websocket-client"],"created_at":"2024-08-01T07:00:38.895Z","updated_at":"2025-06-22T10:36:22.063Z","avatar_url":"https://github.com/pvarentsov.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e🔄 iola\u003c/h1\u003e \n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/pvarentsov/iola/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/pvarentsov/iola\" alt=\"license\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/iola\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/iola.svg\" alt=\"npm\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/iola\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dt/iola.svg\" alt=\"downloads\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e \n  \u003c!-- \u003ca href=\"https://sonarcloud.io/project/overview?id=pvarentsov_iola\"\u003e\n    \u003cimg src=\"https://img.shields.io/sonar/quality_gate/pvarentsov_iola/main?server=https%3A%2F%2Fsonarcloud.io\" alt=\"quality\" /\u003e\n  \u003c/a\u003e  \n  \u003ca href=\"https://sonarcloud.io/project/overview?id=pvarentsov_iola\"\u003e\n    \u003cimg src=\"https://img.shields.io/sonar/coverage/pvarentsov_iola/main?server=https%3A%2F%2Fsonarcloud.io\" alt=\"coverage\" /\u003e\n  \u003c/a\u003e --\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eTable of contents\u003c/b\u003e (click to open)\u003c/summary\u003e\n  \u003cul\u003e\n    \u003cli\u003e\u003ca href=\"#description\"\u003eDescription\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cul\u003e\n      \u003cli\u003e\u003ca href=\"#cli\"\u003eCLI\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#rest-api\"\u003eREST API\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n    \u003cli\u003e\u003ca href=\"#websocket\"\u003eWebSocket\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#socketio\"\u003eSocket.IO\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#tcp--unix-socket\"\u003eTCP \u0026 Unix socket\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/details\u003e\n\n## Description\n\n**iola** - a command-line socket client with REST API. It helps to work with socket servers using your favorite REST client.\n\n\u003cp align=\"center\"\u003e \n  \u003cimg src=\"doc/cli.png\"\u003e\n\u003c/p\u003e\n\n**iola** tries to simplify socket server testing and support the most popular socket clients.\nThe main way to interact with the tool is the REST API. \nThis approach allows you to use the rich functionality of modern REST clients to work with sockets.\n\nThe potential of the tool is revealed when using API clients such as [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), etc.\nYou can manage collections of requests for projects that have socket-based API, use dynamic variables in requests and many other features supported by these clients.\n\n**Features:**\n\n1. Allows reading and sending messages via REST API\n2. Logs all socket events in the console\n3. Has Swagger UI for REST API\n4. Works on Linux, macOS and Windows\n\n**Supported clients:**\n\n1. WebSocket\n2. Socket.IO\n3. TCP\n4. Unix socket\n\n## Installation\n\n**Via npm** (for all platforms where [Node.js](https://nodejs.org/en/) \u003e= 12 installed).\n\n```bash\n$ npm install -g iola\n```\n\n**Via homebrew** (Linux, macOS).\n```bash\n$ brew tap pvarentsov/iola\n$ brew install iola\n```\n\n**Via scoop** (Windows).\n```bash\n$ scoop bucket add iola https://github.com/pvarentsov/scoop-iola.git\n$ scoop install iola\n```\n\n**Or download** standalone binary from [releases](https://github.com/pvarentsov/iola/releases) (Linux, macOS, Windows).\n\n## Usage\n\n### CLI\n\n\u003cpre\u003e\n$ iola --help\n\n\u003cb\u003eiola\u003c/b\u003e - a socket client with REST API\n\nUsage: iola [options] [command]\n\nOptions:\n  --version                 Display version\n  --help                    Display help\n\nCommands:\n  ws [options] \u0026lt;address\u0026gt;    Run websocket client\n  io [options] \u0026lt;address\u0026gt;    Run socket.io client\n  tcp [options] \u0026lt;address\u0026gt;   Run tcp client\n  unix [options] \u0026lt;address\u0026gt;  Run unix client\n  help [command]            Display help for command\n\nAPI:\n  GET  /messages            Get message list\n  GET  /messages/{id}       Get message by id\n  POST /messages            Send message \n  GET  /swagger             Get swagger\n\u003c/pre\u003e\n\n### REST API\n\u003e **Note**: These examples use [HTTPie](https://httpie.io) as the REST API client.\n\n#### Send any data\n```shell\n# Send string message\n$ http POST http://127.0.0.1:3000/messages data='Hi, Server!'\n{\n    \"messageId\": 1\n}\n\n# Get string message by id\n$ http GET http://127.0.0.1:3000/messages/1\n{\n    \"id\": 1,\n    \"date\": \"2022-07-15T21:48:19.939Z\",\n    \"message\": {\n        \"data\": \"Hi, Server!\",\n        \"format\": \"string\"\n    },\n    \"type\": \"SentMessage\"\n}\n\n# Send json string message\n$ http POST http://127.0.0.1:3000/messages data:='{\"message\":\"Hi, Server!\"}'\n{\n    \"messageId\": 2\n}\n\n# Get json string message by id\n$ http GET http://127.0.0.1:3000/messages/2\n{\n    \"id\": 2,\n    \"date\": \"2022-07-15T22:16:31.887Z\",\n    \"message\": {\n        \"data\": {\n            \"message\": \"Hi, Server!\"\n        },\n        \"format\": \"json\"\n    },\n    \"type\": \"SentMessage\"\n}\n```\n\n#### Send binary data\n```shell\n# Send byte-array message\n$ http POST http://127.0.0.1:3000/messages bytes:='[72,101,108,108,111,33]'\n{\n    \"messageId\": 1\n}\n\n# Get byte-array message by id\n$ http GET http://127.0.0.1:3000/messages/1\n{\n    \"id\": 1,\n    \"date\": \"2022-07-15T22:23:32.591Z\",\n    \"message\": {\n        \"data\": [72,101,108,108,111,33],\n        \"format\": \"byte-array\",\n        \"size\": 6\n    },\n    \"type\": \"SentMessage\"\n}\n```\n\nAll clients support `--binary-encoding \u003cencoding\u003e` option for more readability of sent and received binary messages.\n```shell\n# Run iola client with --binary-encoding option\n$ iola ws ws://127.0.0.1:8080 --binary-encoding utf8\n\n# Send byte-array message\n$ http POST http://127.0.0.1:3000/messages bytes:='[72,101,108,108,111,33]'\n{\n    \"messageId\": 1\n}\n\n# Get sent byte-array message by id\n$ http GET http://127.0.0.1:3000/messages/1\n{\n    \"id\": 1,\n    \"date\": \"2022-07-15T22:23:32.591Z\",\n    \"message\": {\n        \"data\": [72,101,108,108,111,33],\n        \"format\": \"byte-array\",\n        \"size\": 6,\n        \"utf8\": \"Hello!\"\n    },\n    \"type\": \"SentMessage\"\n}\n\n# Get received byte-array message by id\n$ http GET http://127.0.0.1:3000/messages/2\n{\n    \"id\": 2,\n    \"date\": \"2022-07-15T22:23:32.591Z\",\n    \"message\": {\n        \"data\": [72,105,44,32,73,111,108,97,33],\n        \"format\": \"byte-array\",\n        \"size\": 9,\n        \"utf8\": \"Hi, Iola!\"\n    },\n    \"type\": \"ReceivedMessage\"\n}\n```\n\n#### List messages\n```shell\n# List messages\n$ http GET http://127.0.0.1:3000/messages\n[\n    {\n        \"id\": 1,\n        \"date\": \"2022-07-15T22:26:57.442Z\",\n        \"message\": {\n            \"data\": \"Hi, Server\",\n            \"format\": \"string\"\n        },\n        \"type\": \"SentMessage\"\n    },\n    {\n        \"id\": 2,\n        \"date\": \"2022-07-15T22:26:57.445Z\",\n        \"message\": {\n            \"data\": \"Hi, Iola!\",\n            \"format\": \"string\"\n        },\n        \"type\": \"ReceivedMessage\"\n    }\n]\n```\n\n#### Swagger\n\nTo get to know the REST API in more detail you can see a swagger that is exposed on the `/swagger` path.\n\n## WebSocket\n\n\u003cpre\u003e\n$ iola help ws\n\nUsage: iola ws [options] \u0026lt;address\u0026gt;\n\nRun websocket client\n\nOptions:\n  --api-port \u0026lt;port\u0026gt;             Set api port (default: \"3000\")\n  --api-host \u0026lt;host\u0026gt;             Set api host (default: \"127.0.0.1\")\n  --header \u0026lt;key:value...\u0026gt;       Set http headers\n  --reply-timeout \u0026lt;timeout\u0026gt;     Set reply timeout in ms (default: \"1000\")\n  --binary-encoding \u0026lt;encoding\u0026gt;  Set binary encoding (choices: \"ascii\",\"utf8\",\"base64\",\"hex\")\n  --no-emoji                    Disable emoji\n  --help                        Display help\n\nExamples: \n  $ iola ws ws://127.0.0.1:8080 \n  $ iola ws ws://127.0.0.1:8080/?token=secret \n  $ iola ws ws://127.0.0.1:8080 --header authorization:\"Bearer token\"\n  $ iola ws ws://127.0.0.1:8080 --binary-encoding utf8 \n  $ iola ws ws://127.0.0.1:8080 --reply-timeout 3000 --no-emoji\n\u003c/pre\u003e\n\n### Message formats\n* string\n* json\n* byte-array\n\n### Server replies\n\nYou can pass the RequestId to the request with json data to await the server reply with such RequestId in the reply data.\nRequestId field can be one of the following:\n* requestId\n* request_id\n* reqId\n* req_id\n* traceId\n* trace_id\n\n```shell\n$ http POST http://127.0.0.1:3000/messages data:='{\"requestId\":\"1\",\"message\":\"Hi, Server!\"}'\n{\n    \"messageId\": 1,\n    \"reply\": {\n        \"data\": {\n            \"requestId\": \"1\",\n            \"message\": \"Hi, Iola!\"\n        },\n        \"format\": \"json\"\n    }\n}\n```\n\n## Socket.IO\n\n**iola** relies on Socket.IO v4. Please check a [version compatibility](https://socket.io/docs/v4/client-installation/#Version-compatibility).\n\n\u003cpre\u003e\n$ iola help io\n\nUsage: iola io [options] \u0026lt;address\u0026gt;\n\nRun socket.io client\n\nOptions:\n  --api-port \u0026lt;port\u0026gt;             Set api port (default: \"3000\")\n  --api-host \u0026lt;host\u0026gt;             Set api host (default: \"127.0.0.1\")\n  --header \u0026lt;key:value...\u0026gt;       Set http headers\n  --auth \u0026lt;key:value...\u0026gt;         Set authentication payload\n  --transport \u0026lt;transport\u0026gt;       Set transport (choices: \"websocket\",\"polling\")\n  --reply-timeout \u0026lt;timeout\u0026gt;     Set reply timeout in ms (default: \"1000\")\n  --binary-encoding \u0026lt;encoding\u0026gt;  Set binary encoding (choices: \"ascii\",\"utf8\",\"base64\",\"hex\")\n  --no-emoji                    Disable emoji\n  --help                        Display help\n\nExamples: \n  $ iola io http://127.0.0.1:8080 \n  $ iola io http://127.0.0.1:8080/?token=secret --transport websocket\n  $ iola io http://127.0.0.1:8080 --header authorization:\"Bearer token\"\n  $ iola io http://127.0.0.1:8080 --auth user:iola --auth pass:qwerty1\n  $ iola io http://127.0.0.1:8080 --binary-encoding utf8 \n  $ iola io http://127.0.0.1:8080 --reply-timeout 3000 --no-emoji\n\u003c/pre\u003e\n\n### Message formats\n* string\n* number\n* boolean\n* null\n* json\n* byte-array\n\n### Transports\n\nClient supports \"websocket\" and \"polling\" transports. It tries to use \"websocket\" first, if available.\nYou can explicitly set the type of transport using `--transport \u003ctransport\u003e` option.\n\n### Auth\n\nSocket.IO client can send [auth credentials](https://socket.io/docs/v4/middlewares/#sending-credentials) using `--auth \u003ckey:value...\u003e` option.\n\n### Pass event\n\nYou can pass event name to sending message. Default event name - `*`.\n\n```shell\n$ http POST http://127.0.0.1:3000/messages event='greeting' data='Hi, Server!'\n{\n    \"messageId\": 1,\n    \"reply\": {\n        \"data\": {\n            \"message\": \"Hi, Iola!\"\n        },\n        \"event\": \"greeting\",\n        \"format\": \"json\"\n    }\n}\n```\n\n### Server replies\n\nSocket.IO client supports server replies by default.\n\n## TCP \u0026 Unix socket\n\nTCP and Unix socket clients have the same api. \n\n\u003cpre\u003e\n$ iola help tcp|unix\n \nUsage: iola tcp|unix [options] \u0026lt;address\u0026gt;\n\nRun tcp|unix client\n\nOptions:\n  --api-port \u0026lt;port\u0026gt;             Set api port (default: \"3000\")\n  --api-host \u0026lt;host\u0026gt;             Set api host (default: \"127.0.0.1\")\n  --sync                        Enable sync mode\n  --reply-timeout \u0026lt;timeout\u0026gt;     Set reply timeout in ms (sync mode only) (default: \"1000\")\n  --binary-encoding \u0026lt;encoding\u0026gt;  Set binary encoding (choices: \"ascii\",\"utf8\",\"base64\",\"hex\")\n  --no-emoji                    Disable emoji\n  --help                        Display help\n\nExamples: \n  $ iola tcp 127.0.0.1:8080 \n  $ iola tcp 127.0.0.1:8080 --sync \n  $ iola tcp 127.0.0.1:8080 --binary-encoding utf8 \n  $ iola tcp 127.0.0.1:8080 --no-emoji\n\n  $ iola unix ./unix.sock\n  $ iola unix ./unix.sock --sync\n  $ iola unix ./unix.sock --binary-encoding utf8 \n  $ iola unix ./unix.sock --no-emoji\n\u003c/pre\u003e\n\n### Message formats\n* byte-array\n\n### Modes\n\nClients support async and sync modes and use async mode by default.\n\nIn async mode, the client and the server exchange messages independently within one connection.\n\nSync mode uses a request/response protocol. The client opens a new connection for each request. \nThe connection will be closed either on the server side after a successful response or by a timeout on the client side.\nTo enable sync mode you need to set `--sync` option.\n\n### Server replies\n\nServer replies are supported only in sync mode.\nIf the server does not close the connection after receiving the request, the client will close it itself by reply timeout.\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/pvarentsov/iola/blob/main/LICENSE).\n","funding_links":[],"categories":["Development","Projects using NestJS","Packages","Command-Line Interface (CLI) Tools","\u003ca name=\"webdev\"\u003e\u003c/a\u003eWeb development"],"sub_categories":["Chat","Protocols and APIs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvarentsov%2Fiola","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpvarentsov%2Fiola","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvarentsov%2Fiola/lists"}