Usage
Aliases
computers
Commands
Inherited flags
Subcommand reference
idyl computer branches
List the branches of a Computer’s history. A branch is the entries that leave
another path at one point, identified as {segment}.{afterSeq}, with its
entry and version counts and its tips. The branch holding the current point
is marked current.
A Computer operand is its name, or its ID in the canonical form
(lowercase 8-4-4-4-12 hexadecimal), which addresses the Computer by ID.
—name <branch-id>=<name> names a branch, and —unname <branch-id> removes
its name; names are unique within the Computer. —trash <branch-id> moves a
branch to Trash and waits until it is there: its versions stay complete and
restorable with ‘idyl computer trash —restore’ until they are deleted
forever. The branch holding the current point cannot be moved to Trash.
Naming and Trash print the branch or Trash entry instead of a list.
—limit requests a page size, and —continue resumes a listing with the value
the previous page returned. JSON and YAML preserve the server’s envelope.
Usage
Flags
Examples
idyl computer commit
Save the Computer’s current files and wait for its recorded outcome.
The result is saved as a new version, unchanged at the existing version, or
failed with the server’s reason. This command does not run a process.
A Computer operand is its name, or its ID in the canonical form
(lowercase 8-4-4-4-12 hexadecimal), which addresses the Computer by ID.
—idempotency-key identifies this request. Reuse the same key and request to
recover an uncertain outcome without starting another save. When omitted,
the CLI chooses a key and reports it if the wait is interrupted.
Ctrl-C stops waiting; the recorded operation may still complete.
Usage
Flags
Examples
idyl computer cp
Copy files or directories between this machine and a Computer. Exactly one
operand is name[@version]:path, where name may also be the Computer’s ID.
Computer paths are relative POSIX paths; name: addresses the root. Prefix a
local path containing a colon with ./.
Downloads read one saved version throughout the copy. —save-first saves
the current files first and reads precisely that version. Uploads publish
one new version, reported as “saved as vN”; @version selects the upload’s
base, preserving later machine saves on other paths. A directory upload puts
its contents under the destination path; an empty path puts them at the
Computer root.
A local operand of - streams a POSIX tar archive instead of a local path: a
download writes the saved tree below the path to standard output, and an
upload reads an archive from standard input and puts its entries under the
destination path. Status is written to standard error.
Symbolic links are copied as links, never followed. File modes are retained;
ownership and timestamps are not. The local filesystem must support each
saved name. Downloads replace each file only after its complete size and hash
have been checked. A failed directory copy may leave files already copied,
but never a partially replaced file.
—idempotency-key identifies an upload or a save-first request. Reuse the
same key and unchanged request after an uncertain response. Ctrl-C stops
the transfer or wait; an admitted publication may still complete.
Usage
Flags
Examples
idyl computer create
Create a Computer in the resolved Namespace and subnet.
A Computer lives in the subnet it is created in, and that never changes: a
Computer needed in another subnet is created there as a new Computer. The
name must be unique among the live Computers of the Namespace in the subnet.
—idle-timeout sets how long the Computer keeps its execution after its last
session ends: “never”, or a nonnegative whole number followed by s, m, or h.
Zero is sent as 0s. The server validates the requested timeout and states it
in seconds, so 5m reads back as 300s. A Computer
created without one keeps its execution for 300s.
—size requests the enforced on-disk amount and —headroom reserves space for
outstanding changes. —store selects an admitted Store at creation and cannot
be changed later. The server applies storage defaults and admission policy.
—save-on-exec=false disables automatic end-of-exec saves; when omitted,
automatic saving is enabled. —save-window sets the allowed failing-save
time, subject to the server’s policy caps.
The OS image is chosen at creation: —image names an IDYL image from the
subnet’s catalog (‘idyl computer images’ lists it), and —image-ref names an
own OCI image, used exactly as given. A Computer created with neither runs
the catalog’s default image, recorded by its name; its image changes only
when ‘idyl computer edit’ names another.
—cpu and —memory set the computer’s limits, and —network-class its
network: internet (the public internet, with every local network blocked),
restricted-egress (only the destinations —egress-allow lists, each dns or
tcp:<port>:<host>), or none. —egress-allow alone makes the network
restricted-egress. “default”, or no flag, leaves a setting to the subnet’s
default, which applies at each start; a Computer reaches the internet unless
its subnet’s default says otherwise. —env sets an environment variable for every
process of the computer, sessions included. Its value is readable by everyone
who may read the Computer, so it is not a place for secrets.
A change to the execution settings takes effect from its next start and never disturbs
a command already running, and each change is an entry in ‘idyl computer
history’.
Usage
Flags
Examples
idyl computer delete
Delete a Computer from the resolved Namespace and subnet.
Deletion is asynchronous. The platform accepts it, records the Computer as
terminating, releases what the Computer holds, and finalizes on its own;
once finalized the name no longer resolves and may be reused. Nothing else in
the Namespace is touched. While it is terminating the Computer still reads.
Deleting a Computer that is already terminating is accepted again.
—wait blocks until the Computer is finalized and exits the way ‘idyl wait’
does: 0 finalized, 124 when —timeout passes first. Without it the command
returns as soon as the deletion is accepted. With -o json or -o yaml the
command prints the platform’s answer to the delete, or with —wait the wait’s
result.
You will be prompted for confirmation unless the —yes flag is provided.
Usage
Aliases
rm
Flags
Examples
idyl computer edit
Edit how a Computer in the resolved Namespace and subnet runs.
Each flag changes one setting, and every setting no flag names keeps the value
it has: edit sends only the changes, the platform merges them into the
settings in force, and the Computer is never read first.
—set-idle-timeout sets how long the Computer keeps its execution after its
last session ends: “never”, or a nonnegative whole number followed by s, m, or h.
Zero is sent as 0s. The server validates the requested timeout. An accepted
timeout takes effect at once and is measured from when the
Computer last became idle, so its execution is released if it has already
been idle for longer than a shortened timeout. The platform states it in seconds, so 5m reads
back as 300s. The idle timeout is not part of the execution settings, so it is not
recorded in the Computer’s history.
—set-size and —set-headroom request storage settings. The server reports a
pending reservation when the running writer cannot apply them yet; an
accepted request does not mean the new disk reservation is already in force.
The Store is fixed at creation.
—set-save-on-exec=false disables automatic end-of-exec saves; =true enables
them. —set-save-window changes the allowed failing-save time, subject to
server policy. Settings omitted from this command keep their current values.
—set-image names another IDYL image from the subnet’s catalog (‘idyl
computer images’ lists it), and —set-image-ref an own OCI image, used
exactly as given. —set-cpu and —set-memory set the computer’s limits.
—set-network-class replaces the computer’s network: internet (the public
internet, with every local network blocked), restricted-egress (only the
destinations —set-egress-allow lists, each dns or tcp:<port>:<host>), or
none. The network is replaced whole: —set-egress-allow states the whole
allow list and makes the network restricted-egress, and restricted-egress
without it allows no destination.
“default” returns the CPU, memory, or network to the subnet’s default, as it
stands at each start.
—add-env sets an environment variable for every process of the computer,
sessions included, replacing one of the same name, and —remove-env removes
one; removing a variable the Computer does not have changes nothing. A
variable’s value is readable by everyone who may read the Computer, so it is
not a place for secrets.
A change to the execution settings takes effect from its next start and never disturbs
a command already running: while sessions run, the computer keeps the
settings it started with, and edit says the change applies when they end.
Each change is an entry in ‘idyl computer history’.
Usage
Flags
Examples
idyl computer exec
Run a command in a Computer in the resolved Namespace and subnet.
The command and its arguments follow a — separator. A dormant Computer is
woken to run it, so the command may wait until its session is ready; on a
terminal, what it waits for, such as the Computer waking or capacity to run
it on, is written to stderr. The platform bounds the wait, and a session that
cannot become ready is reported with its reason. Interactive TTY sessions
require both —interactive and —tty. The command’s output is written as it
arrives, byte for byte, and the CLI exits with the command’s exit code.
After the remote process exits, the CLI waits for its recorded save outcome
and reports the version it ran at, its streamed exit code, and the save on
stderr. A failed save exits 75, including when the command itself failed;
the summary still states the command’s exit code. Disabling automatic saves
is reported as save off. Ctrl-C stops waiting without cancelling a command
that already ran or its save. Detaching a TTY returns without waiting for
that process or claiming an exit or save outcome.
The session’s credential is checked before any connection is made: it must
name the one Computer execution the platform bound the session to. A session
that is refused, or interrupted, before it attaches is cancelled.
In an Actor’s Computer whose Agent execution is live, the session is refused,
or fails, with AGENT_EXECUTION_LIVE and the Agent’s work is left undisturbed.
—interrupt fences that execution first, as ‘idyl actor interrupt’ does,
discarding its unsaved work; it requires computer:update and changes nothing
when no Agent execution is live.
Usage
Flags
Examples
idyl computer files
List the entries of one saved Computer directory, or delete and rename saved
paths. The operand is name[@version][:path]; without a path it is the root,
and without @version the latest saved version, or with —save-first the
version a save of the current files returns.
A Computer operand is its name, or its ID in the canonical form
(lowercase 8-4-4-4-12 hexadecimal), which addresses the Computer by ID.
A listing shows each entry’s type, permission bits, size, and name, and a
symbolic link’s target; a file’s SHA-256 is in JSON and YAML. Every name is
shown with its non-printable characters escaped. A listing reads exactly one
saved version, which is written to standard error; —limit requests a page
size, and —continue resumes with the value the previous page returned. JSON
and YAML preserve the server’s listing envelope.
—delete <path> and —rename <from>=<to> change saved files: every change
the command names is published together as one new version, reported as
“saved as vN”, on @version when given and otherwise on the current files.
Deleting a directory deletes what it contains. A rename’s source is split
from its destination at the first =; destination names must be UTF-8 in
NFC form. Earlier versions keep the old files, so ‘idyl computer restore’
brings them back.
—idempotency-key identifies a change or a save-first request. Reuse the
same key and unchanged request after an uncertain response.
Usage
Flags
Examples
idyl computer fork
Copy a saved Computer version and its history into a new Computer in the
same Namespace and subnet. Use v2 or a saved-version name after @. The source
version’s immutable owning journal entry fixes the copy; later changes or
deletion of the source do not change the new Computer. Running sessions and
execution authority are not copied.
A Computer operand is its name, or its ID in the canonical form
(lowercase 8-4-4-4-12 hexadecimal), which addresses the Computer by ID.
The command waits for the new Computer’s recorded fork outcome. Ctrl-C
stops waiting without cancelling the copy. Reuse —idempotency-key with the
same request to find its recorded outcome after an uncertain response.
When omitted, the CLI chooses a key and reports it if recovery is needed.
Usage
Flags
Examples
idyl computer get
Get details of a Computer, or list Computers in the resolved Namespace
and subnet.
With no arguments, lists the computers —owner selects (by default, those no
Actor manages). With a name argument, shows that Computer: its owning Actor
when one manages it, its phase, whether anything is
executing on its behalf, its head version, its idle timeout, and its
execution settings: the OS image it runs, with the patch level of an IDYL image, its
CPU, memory, network, and environment variables, each default marked as one with
the value its next start uses, and whether the computer still runs on
earlier settings until the sessions running now end.
Usage
Flags
Examples
idyl computer go-back
Move the Computer’s current point back to a saved version (v41 or its
name) or a journal entry ID, or with —undo to where the last go-back left.
The files become the version at that point, and the next change starts a new
branch from it. Nothing is deleted: the entries left behind stay as a branch,
which this command names, and ‘idyl computer branches’ lists. Unsaved work of
a running writer is discarded, and its next start begins at the new point.
A Computer operand is its name, or its ID in the canonical form
(lowercase 8-4-4-4-12 hexadecimal), which addresses the Computer by ID.
The command waits for the move’s recorded outcome. —idempotency-key
identifies the request; reuse it with the same request after an uncertain
response. JSON and YAML print the move.
Usage
Flags
Examples
idyl computer history
Show a Computer’s history, newest first: one entry for every session run in
it, whatever client created the session, and one for every change to its
execution settings.
Each entry shows its position, its ID, when the platform admitted it, its
state (running, ended, or error with the reason the session never ran), how
its process ended (its exit code, the signal that ended it, or unknown), who
created the session, from which client, how it ran (exec, ssh-exec, or
ssh-shell), and its command. An exec command is shown as a shell command
line, an SSH command as the text the SSH client sent, and an interactive
shell as its executable.
An execution-settings entry shows who made the change, from which client, and what it
changed in its command column, with the mode “execution-settings”: the image, CPU,
memory, or network it set, where “default” means the setting was removed, and
each environment variable set as +NAME or removed as -NAME. An image patch, made
by IDYL when the Computer starts on a newer patch level of its IDYL image,
reads “image patched” with the image and the patch levels it moved between.
With an entry ID, an execution-settings entry is shown with the whole settings after it.
Every character that is not printable is shown as an escape, so an entry can
never write to the terminal reading it. A table row shows a long command or
change cut short, ending in …; with an entry ID, the entry is shown whole.
Anyone who may read the Computer sees every entry, the values of environment
variables included. Standard input and
keystrokes are never recorded. A session’s exit code is part of its entry and
never becomes this command’s exit status.
A page holds up to —limit entries (50 when not given, at most 200). When more
entries follow, the next page’s —continue value is written to stderr in
table output and is the “continue” field in JSON and YAML. A listing that is
continued never shows entries admitted after its first page. JSON and YAML
also carry the journal’s genesis entry, which records nothing and is not
shown in the table.
Usage
Flags
Examples
idyl computer images
List the IDYL image catalog of the resolved subnet: the OS images a
Computer there can run, named with —image on ‘idyl computer create’ and
—set-image on ‘idyl computer edit’.
Each image shows its catalog name, what it holds beyond its OS, its OS and
version, its current patch level, and whether it is the default a Computer
created without —image runs. IDYL keeps each image patched: a Computer on
an IDYL image runs its newest patch level from its next start, and its
history records the patch. Another OS or version is another image with
another name. The catalog is the same for every Namespace in the subnet.
Usage
Flags
Examples
idyl computer list
List the Computers in the resolved Namespace and subnet.
By default the list holds only Computers you created. A Computer an Actor
manages is listed with —owner all, which includes every owner, or —owner
<actor-id>, which selects that Actor’s Computer. Either selection checks the
same Namespace and subnet permissions, and an Actor’s Computer is always
reachable directly by its ID.
Usage
Aliases
ls