cli_effects_reference.md

name	CLI effects reference
description	Reference for effects implemented by the eyg CLI .

EYG separates the declaration of an effect (in your script: perform Foo(...)) from its implementation (provided by the runner). The CLI in this repository (packages/gleam_cli) implements the effects below.

For scripts that need value-based restrictions around Fetch and the result-returning file-system effects, see overlay.access.

File system

Relative filesystem paths are resolved from directory of the source expression that performs the effect. Inline code, shared and published modules have no source directory using a relative path will always fail. Use perform CWD({}) to build an absolute path for reading relative to a scripts running location.

ReadFile

Read a slice of a file at a given byte offset.

match perform ReadFile({path: "data.txt", offset: 0, limit: 1000000}) {
  Ok(bytes) -> {
    match !string_from_binary(bytes) {
      Ok(text) -> { text }
      Error(_) -> { !never(perform Abort("not valid utf-8")) }
    }
  }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Field	Type	Notes
path	String	Absolute or relative to the source expressions directory
offset	Int	Byte offset to start reading from
limit	Int	Maximum bytes to read

Returns Result(Binary, String).

WriteFile

Overwrite a file with new contents (creating it if necessary).

perform WriteFile({path: "out.txt", contents: !string_to_binary("hello")})

Returns Result({}, String).

DeleteFile

Delete a file at the given path. Deleting a file that does not exist is an error, surfaced via the Result return type — callers that want delete-idempotency should match Error(_) and ignore.

perform DeleteFile("scratch.txt")

Returns Result({}, String).

AppendFile

Append bytes to a file. Safe for concurrent appends.

perform AppendFile({path: "log.txt", contents: !string_to_binary("a line\n")})

Returns Result({}, String).

ReadDirectory

List entries in a directory. Excludes . and ...

match perform ReadDirectory(".") {
  Ok(entries) -> { entries }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Returns Result(List({name: String, type: Directory({}) | File({size: Int})}), String).

For a recursive walk, see eyg_packages/fs/index.eyg's list and list_files helpers.

CWD

Return the Current Working Directory (CWD) where the eyg process was started.

let cwd = perform CWD({})

Argument is unit ({}). Returns Ok(String) | Error({}).

I/O

Now

Returns the current wall-clock time as Unix epoch milliseconds.

let millis = perform Now({})

Argument is unit ({}). Returns Int.

Print

Write a string to stdout. No newline is added.

perform Print("hello\n")

Returns {}.

Random

Returns a uniformly random integer greater than 0 and less than max.

let dice = !int_add(perform Random(6), 1)

Argument is unit ({}). Returns Int.

Sleep

Suspends the script for the given number of milliseconds. Other effects in flight still progress.

let _ = perform Sleep(1000)  // wait 1 second

Argument is Int (milliseconds). Returns unit ({}).

Env

Read a process environment variable.

match perform Env("HOME") {
  Some(value) -> { value }
  None({}) -> { "" }
}

Argument is String (the variable name). Returns Option(String).

Network

Fetch

Make an HTTP request.

let request = {
  method: GET({}),
  scheme: HTTP({}),
  host: "example.com",
  port: None({}),
  path: "",
  query: None({}),
  headers: [],
  body: !string_to_binary("")
}
match perform Fetch(request) {
  Ok({status, headers, body}) -> { status }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Returns Result({status: Int, headers: List(...), body: Binary}, String).

Parsing

DecodeJSON

Parse a JSON binary into a flat list of {term, depth} events.

match perform DecodeJSON(!string_to_binary("{\"x\": 1}")) {
  Ok(events) -> { events }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Each event's term is one of: True | False | Null | Integer i | String s | Number {…} | Array | Object | Field name.

EYGParse

Parse EYG source text into the canonical flat AST representation.

match perform EYGParse("let x = 1\nx") {
  Ok(nodes) -> { nodes }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Argument is String. Returns Ok(List(AstNode)) | Error(String). AST nodes appear in pre-order and their fixed-arity children follow them in the list. The CLI accepts both text syntax and DAG JSON through this effect.

Cryptography

For design rationale and extension guidance, see Crypto effects.

Hash

Compute a cryptographic digest of a binary.

let digest = perform Hash({algorithm: SHA256({}), bytes: !string_to_binary("abc")})

Field	Type	Notes
algorithm	SHA256({})	The hash algorithm to use
bytes	Binary	The data to hash

Returns Binary (the raw digest).

CreateKey

Generate a key pair for a named algorithm.

let key = match perform CreateKey(Eddsa({})) {
  Ok(key) -> { key }
  Error(reason) -> { !never(perform Abort(reason)) }
}

The request is an open algorithm variant. Currently the CLI supports Eddsa({}), which generates an Ed25519 key and returns Ok(Eddsa({kty: "OKP", crv: "Ed25519", x, d})); x is the raw public key and d is the raw private seed as binaries.

Sign

Sign a binary with key material in the shape returned by CreateKey.

match perform Sign({key: key, data: !string_to_binary("message")}) {
  Ok(signature) -> { signature }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Returns Result(Binary, String). The signature is the raw Ed25519 signature binary; invalid key material is returned as Error(reason) rather than crashing the host runtime.

Authenticated services

Each of these performs a spotless OAuth flow the first time it's used and caches the token. The lift / lower shape matches Fetch, but the request is rewritten to point at the service's API host with the bearer token attached.

Effect	Host
GitHub	api.github.com
Netlify	api.netlify.com
DNSimple	api.dnsimple.com
Vimeo	api.vimeo.com

let request = {
  method: GET({}),
  scheme: HTTPS({}),
  host: "api.github.com",
  port: None({}),
  path: "/user",
  query: None({}),
  headers: [],
  body: !string_to_binary("")
}
perform GitHub(request)