env
Expose process-level metadata to CX code: environment variables, command-line arguments, and process identity. Read, list, and typed-default environment variables; parse argv into declarative flags and positionals; query process metadata such as PID, executable path, cwd, hostname, and OS/arch; reach the standard stream handles; and terminate the process. The environment is read-only from CX code — there are no setters. This is a Tier B runtime surface and is necessarily impure.
env:var
[$env:var] -> [or string [sequence string]] — Read an environment variable, signaling absence (the empty sequence) when it is unset.
[?lib 'cx-stdlib/env']
[$env:var "CX_DEFINITELY_UNSET_VAR_XYZ_001"]
cx-err:CXER0271
env:vars
[$env:vars] -> map — Return all environment variables as a name-to-value map.
[?lib 'cx-stdlib/env']
[= [$env:vars] [$env:vars]]
cx-err:CXER0271
env:has-var
[$env:has-var] -> bool — Report whether a variable is set, distinguishing set-to-empty from unset.
[?lib 'cx-stdlib/env']
[$env:has-var "CX_DEFINITELY_UNSET_VAR_XYZ_002"]
cx-err:CXER0271
env:var-or-default
[$env:var-or-default] -> string — Read a variable, returning the supplied default when it is unset.
[?lib 'cx-stdlib/env']
[$env:var-or-default "CX_DEFINITELY_UNSET_VAR_XYZ_003" "fallback"]
cx-err:CXER0271
env:var-int
[$env:var-int] -> int — Read a variable as an int, returning the default if unset or raising if set-but-unparseable.
[?lib 'cx-stdlib/env']
[$env:var-int "CX_DEFINITELY_UNSET_VAR_XYZ_004" 8080]
cx-err:CXER0271
env:var-float
[$env:var-float] -> float — Read a variable as a float, returning the default if unset or raising if set-but-unparseable.
[?lib 'cx-stdlib/env']
[$env:var-float "CX_DEFINITELY_UNSET_VAR_XYZ_005" 2.5]
cx-err:CXER0271
env:var-bool
[$env:var-bool] -> bool — Read a variable as a bool (true/false/1/0/yes/no/on/off), returning the default if unset.
[?lib 'cx-stdlib/env']
[$env:var-bool "CX_DEFINITELY_UNSET_VAR_XYZ_006" true]
cx-err:CXER0271
env:var-required
[$env:var-required] -> string — Read a variable, raising a fault if it is unset.
[?lib 'cx-stdlib/env']
[$env:var-required "CX_DEFINITELY_UNSET_VAR_XYZ_007"]
cx-err:CXER0271
env:argv
[$env:argv] -> [sequence string] — Return the program's argument vector: argv[0] names the resource being run, the rest are the program arguments given after it (never cx's own flags).
[?lib 'cx-stdlib/env']
[= [$env:argv] [$env:argv]]
true
env:parse-args
[$env:parse-args] -> element — Parse argv against a spec into an [args] element of flags, positionals, and unparsed extras.
[?lib 'cx-stdlib/env']
[?let [= $spec [argspec [flag name=verbose short=v type=bool]]]
[$env-parse-args $spec ("prog", "--nope")]]
cx-err:CXER2501
env:flag
[$env:flag] -> any — Look up a parsed flag value by name from a parse-args result.
[?lib 'cx-stdlib/env']
[?let [= $spec [argspec [flag name=verbose short=v type=bool] [flag name=limit short=n type=int default=100]]]
[= $parsed [$env-parse-args $spec ("prog", "--verbose", "--limit", "10")]]
[$env:flag $parsed "verbose"]]
true
env:positional
[$env:positional] -> string — Look up a parsed positional argument by name from a parse-args result.
[?lib 'cx-stdlib/env']
[?let [= $spec [argspec [positional name=input-file type=string required=true]]]
[= $parsed [$env-parse-args $spec ("prog", "data.cx")]]
[$env:positional $parsed "input-file"]]
'data.cx'
env:remaining
[$env:remaining] -> [sequence string] — Return the leftover arguments not consumed by declared flags or positionals.
[?lib 'cx-stdlib/env']
[?let [= $spec [argspec [positional name=first type=string]]]
[= $parsed [$env-parse-args $spec ("prog", "a", "b", "c")]]
[$env:remaining $parsed]]
(b, c)
env:usage
[$env:usage] -> string — Render a human-readable usage string from an argument spec, for --help or parse failures.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[?let [= $spec [argspec [flag name=verbose short=v type=bool] [positional name=input-file type=string required=true]]]
[$strings:is-empty [$env:usage $spec]]]
false
env:pid
[$env:pid] -> int — Return the current process ID.
[?lib 'cx-stdlib/env']
[> [$env:pid] 0]
true
env:ppid
[$env:ppid] -> int — Return the parent process ID.
[?lib 'cx-stdlib/env']
[>= [$env:ppid] 0]
true
env:executable-path
[$env:executable-path] -> string — Return the filesystem path of the running executable.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:executable-path]]
cx-err:CXER0271
env:cwd
[$env:cwd] -> string — Return the current working directory.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:cwd]]
cx-err:CXER0271
env:hostname
[$env:hostname] -> string — Return the host machine name.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:hostname]]
cx-err:CXER0271
env:keychain-read
[$env:keychain-read] (service::string account::string) -> [or string [sequence string]] — Read one generic-password item of the OS keychain — macOS Keychain or the Linux Secret Service — by its service and account, signaling absence (the empty sequence) when no such item exists. Charges the keychain capability, which --allow-common does not carry.
[?lib 'cx-stdlib/env']
[$env:keychain-read "cx-example" "nobody"]
cx-err:CXER0271
env:username
[$env:username] -> string — Return the name of the current user.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:username]]
cx-err:CXER0271
env:os-name
[$env:os-name] -> string — Return the operating-system name, such as linux or darwin.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:os-name]]
false
env:os-arch
[$env:os-arch] -> string — Return the CPU architecture, such as amd64 or arm64.
[?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:os-arch]]
false
env:cpu-count
[$env:cpu-count] -> int — Return the logical CPU count, including hyperthreads.
[?lib 'cx-stdlib/env']
[> [$env:cpu-count] 0]
true
env:stdin
[$env:stdin] -> element — Return the standard-input stream handle, to pass to cx-stdlib/io for I/O.
[?lib 'cx-stdlib/env']
[$env:stdin]
[std-stream name=stdin fd=0]
env:stdout
[$env:stdout] -> element — Return the standard-output stream handle, to pass to cx-stdlib/io for I/O.
[?lib 'cx-stdlib/env']
[$env:stdout]
[std-stream name=stdout fd=1]
env:stderr
[$env:stderr] -> element — Return the standard-error stream handle, to pass to cx-stdlib/io for I/O.
[?lib 'cx-stdlib/env']
[$env:stderr]
[std-stream name=stderr fd=2]
env:write-line
[$env:write-line] ($text::string) -> null — Write one line to this invocation's own standard output (fd 1) and flush it, capability-free.
[?lib 'cx-stdlib/env']
[$env:write-line "live line"]
null
env:exit
[$env:exit] -> null — Flush pending I/O, run finalizers, and terminate the process with the given exit code.
[?lib 'cx-stdlib/env']
[$env:exit 0]
[subprocess-harness: child exits with status 0]
env:on-signal
[$env:on-signal] -> null — Run FN (given the signal atom) when this program receives one of SIGNALS (:term, :hup, :int), then exit 128 + the signal number.
[?lib 'cx-stdlib/env']
[$env:on-signal (:term, :hup) [?fn ($sig) [$env:write-line 'stopped']]]
null
env:abort
[$env:abort] -> null — Terminate the process immediately without flushing; use only for unrecoverable corruption.
[?lib 'cx-stdlib/env']
[$env:abort]
[subprocess-harness: child terminates via abort signal]