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.

The platform builds and runs on these targets in CI:

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

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 require a caller-configured timeout covering the whole operation. A zero timeout fails immediately. Tcp.Stream.read_until! and read_line! also require a maximum byte count, preventing an untrusted peer from causing unbounded buffering.
• SQLite keeps up to 16 recently used ordinary path connections open. A live prepared statement keeps its connection open after cache eviction, and reused paths continue sharing that live connection. The exact :memory: path is kept open for the lifetime of its host thread, so repeated use accesses the same in-memory database.

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!.

• 0.21.0-rc4 release documentation
• latest main branch

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

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