basic-cli

A Roc platform for command-line programs.

basic-cli supports command execution, directories, environment variables, files, HTTP, locales, paths, random seeds, sleeping, SQLite, standard input/output/error, TCP, terminal raw mode, and UTC time.

Supported targets

The platform builds and runs on these targets in CI:

Roc target	Operating system	Architecture
x64mac	macOS	x86-64
arm64mac	macOS	ARM64
x64musl	Linux (musl)	x86-64
arm64musl	Linux (musl)	ARM64
x64win	Windows	x86-64

Other targets are not currently supported. In particular, Windows support is x86-64 only.

Host runtime behavior

These current host-level limitations may affect application design:

• HTTP and HTTPS use HTTP/1 only. Issue #455 tracks research into HTTP/2 support and its tradeoffs.
• HTTPS certificates are validated against bundled WebPKI roots, not the operating system trust store. A certificate trusted only through a locally installed OS root will therefore be rejected. Issue #454 tracks research into the appropriate trust configuration for basic-cli.
• The timeout configured on an HTTP Request covers the request and response; NoTimeout leaves it unbounded. Responses are buffered completely without a configurable size limit (issue #436), and several network and TLS failures currently use a generic transport error (issue #438).
• TCP connect, read, and write operations have no caller-configurable timeouts. They can block until the operation completes or the operating system returns an error. Tcp.Stream.read_until! and read_line! also have no size limit and buffer until the delimiter or EOF. Issue #437 tracks timeout and bounded-read APIs.
• SQLite caches one connection per database path for the life of the process. Reusing a path reuses its connection, so repeated use of :memory: accesses the same in-memory database. Using many distinct paths retains all of those connections. Prepared statements are finalized after their last reference is dropped, but the cached connections remain open. Issue #435 tracks connection ownership and cleanup.

Examples

The examples directory contains executable, application-shaped CLI programs for common tasks like reading files, running commands, constructing URLs, making HTTP requests, working with SQLite, and reading stdin.

The examples are pinned to the 0.21.0-rc4 release:

app [main!] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.21.0-rc4/FvCh4vdqm3nBY6DWEfZ8RuGCVfjuMY43HA8KSNk9qVDn.tar.zst" }

To run examples from a local checkout instead, build the platform first and use "../platform/main.roc"; see CONTRIBUTING.md.

HTTP examples use Roc's builtin Json parser and encoder directly through Http.get! and Http.send_json!.

Documentation

• 0.21.0-rc4 release documentation
• latest main branch

Help

Ask questions on Roc Zulip, especially in the #beginners stream.

Contributing

Contributor setup, verification, generated glue, and documentation publishing notes live in CONTRIBUTING.md.