Skip to main content

Run a CLI server

Use Node.js 22.16.0 or later.

npm install -g iosignal-cli
io-server -l 7777

Global installation requires write access to your Node.js installation's global package directory. ios is an alias for io-server. Specify at least one of -l and -L; without either, the command exits with an error.

io-server -l 7777
io-server -L 8888
io-server -l 7777 -L 8888
io-server --help
io-server --version

Use ws://localhost:7777 for WebSocket and cong://localhost:8888 for TCP clients. Arduino takes a hostname and TCP port separately. From another device, use the server's reachable IP/domain. Stop with Ctrl+C; exit is a client command.

Options​

OptionMeaning
-l, --listen <port>WebSocket port
-L, --listen-congport <port>CongSocket TCP port
-d, --auth-file <path>JSON or JavaScript authentication file
-e, --auth-param <id.key.cid[.role[.quota]]>Credentials; separate entries with commas. Role: device (default), service or admin
-r, --auth-redisRedis authentication
-i, --id-keyLocal test: any ID logs in when its key equals the ID (CID = ID)
-k, --shared-key <key>Local test: any ID logs in with the shared key (CID = ID)
-M, --members-onlyDrop signals from connections that are not authenticated
-t, --heartbeat-interval <milliseconds>Liveness check interval; default 50000; range 1000–2147483647
-m, --log-stats <milliseconds>Print a one-line stats summary every N ms; 0 off, otherwise 1000–2147483647
-s, --log-messagesLog each received message's type and tag, never the payload
-q, --anonymous-quota <profile>Quota profile of unauthenticated connections: anonymous (default), basic, pro, unlimited
-f, --file-loggerWrite connection.log, auth.log, attack.log in the working directory
-a, --attach-services [list...]Space-separated reply, sudo, redis; none by default
-o, --show-optionsPrint initial options and attached service names
-V, --version / -h, --helpVersion / help

Ports range from 0 to 65535; 0 lets the OS choose an available port.

Authentication​

io-server -l 7777 --auth-file ./auth_file.json
io-server -l 7777 --auth-param 'uno.uno-key.uno,admin.admin-key.admin.admin'

Replace example credentials for real use. If multiple providers are specified, only one is selected in this order: file, parameter, Redis. Without an authentication option, no provider is configured. Without a quota, a device uses the basic profile and service/admin use unlimited. See file format and access policy.

Local test logins​

From iosignal-cli 8.1.0, --id-key and --shared-key turn on authentication without a key list. The login ID becomes the CID.

io-server -l 7777 -L 8888 --id-key # log in when the key equals the ID
io-client -i dev1 -k dev1

io-server -l 7777 -k lab2026 -M # any ID with the shared key; drop anonymous signals
io-client -i dev1 -k lab2026
  • Anonymous connections are still accepted without -M. -M also works with the other authentication options.
  • Combining --id-key and --shared-key with each other or with another authentication option exits with an error.
  • The start box shows the mode under Authentication; the shared key is not printed.
  • Anyone who knows the rule can log in under any ID, so use them only for tests on a trusted local network. See local test logins.

Quotas​

Every connection follows a quota profile (message size, publish fan-out, message and byte rates, connections per account), always enforced by the server. Unauthenticated connections use the anonymous profile. For local tests with large messages, select another profile such as -q unlimited.

io-server -l 7777 -q unlimited -m 10000 # no limits for anonymous connections, stats every 10 s

Redis and services​

Redis defaults to localhost:6379. REDIS_HOST and REDIS_PORT configure the shared Redis connection used by authentication and services. On macOS/Linux shells:

REDIS_HOST=127.0.0.1 REDIS_PORT=6379 io-server -l 7777 --auth-redis
io-server -l 7777 --auth-redis --attach-services reply redis

The server starts after Redis connects. Connection timeout is five seconds, automatic reconnection is disabled, failure exits with code 1, and shutdown closes Redis.

To try a service, start io-server -l 7777 --attach-services reply, then enter call reply echo hello in a client. The sudo service must be explicitly attached. sudo accepts only connections logged in with the admin role and redis only service or higher, so combine them with an authentication option. The duplicate login policy cannot be set from the CLI yet and follows the library default. See client commands.