> ## Documentation Index > Fetch the complete documentation index at: https://docs.idyl.network/llms.txt > Use this file to discover all available pages before exploring further. # idyl computer > Manage computers in a namespace Manage the Computers of a Namespace. A Computer is one durable logical computer: it keeps its state whether or not anything is executing on its behalf. A Computer lives in the subnet it is created in, so every command addresses the subnet selected by --subnet, IDYL\_SUBNET, or the current context. Names are unique within a Namespace and subnet together. A Computer is created deliberately; Accounts do not receive a default one. ## Usage ```bash theme={null} idyl computer ``` ## Aliases * `computers` ## Commands | Command | Description | | - | - | | `idyl computer branches` | List, name or discard branches of a computer's history | | `idyl computer commit` | Save a computer's current files | | `idyl computer cp` | Copy files between this machine and saved computer versions | | `idyl computer create` | Create a computer | | `idyl computer delete` | Delete a computer | | `idyl computer edit` | Edit a computer | | `idyl computer exec` | Run a command in a computer | | `idyl computer files` | List, delete or rename saved computer files | | `idyl computer fork` | Create a computer from a saved version and its history | | `idyl computer get` | Get computer details or list all computers | | `idyl computer go-back` | Go back to an earlier point in a computer's history | | `idyl computer history` | Show the history of a computer | | `idyl computer images` | List the IDYL images a computer can run | | `idyl computer list` | List computers | | `idyl computer restore` | Restore saved files as a new computer version | | `idyl computer ssh` | Connect to a computer with OpenSSH | | `idyl computer trash` | List, restore or delete forever branches in a computer's Trash | | `idyl computer versions` | List or name saved computer versions | ## Inherited flags | Flag | Description | | - | - | | `-a , --account-id ` | Account ID to use, overriding the current context. | | `-c , --context ` | Use the named context for this command. | | `--homedir ` | Override the configuration directory. Defaults to \~/.config/idyl. | | `-n , --namespace ` | Namespace to address, overriding the entered context. | | `--network ` | Override the Network for this command. | | `-p , --profile ` | Override the access profile for this command. | | `-s , --subnet ` | Subnet to use for this command, overriding the current context. | ## 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 \=\ names a branch, and --unname \ removes its name; names are unique within the Computer. --trash \ 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 ```bash theme={null} idyl computer branches [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Opaque continuation value returned by the previous page. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `--limit ` | Maximum branches in one page; the server chooses the default when omitted. Default: `0`. | | `--name ` | Name a branch, as \=\. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--trash ` | Move a branch to Trash. | | `--unname ` | Remove a branch's name. | #### Examples ```bash theme={null} idyl computer branches payments idyl computer branches payments --name 3.12=experiment idyl computer branches payments --trash 3.12 ``` ### `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 ```bash theme={null} idyl computer commit [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl computer commit payments idyl computer commit payments --idempotency-key before-cleanup -o json ``` ### `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 ```bash theme={null} idyl computer cp [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--save-first` | Save current files before a download; cannot be combined with @version. | #### Examples ```bash theme={null} idyl computer cp ./report.txt payments:report.txt idyl computer cp ./assets payments:assets idyl computer cp payments@v2:report.txt ./report.txt idyl computer cp 01954e20-7540-7ec4-93ec-14f783e6ab35@v2:assets ./assets idyl computer cp payments:assets ./backup --save-first idyl computer cp payments@v2:assets - > assets.tar tar -cf - -C ./site . | idyl computer cp - payments:site ``` ### `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:\:\), 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 ```bash theme={null} idyl computer create [flags] ``` #### Flags | Flag | Description | | - | - | | `--cpu ` | CPU limit of the computer, such as 500m or 2, or "default" for the subnet's default. | | `--egress-allow ` | Destination a restricted-egress computer may reach: dns, or tcp:\:\; repeatable, and together the whole list. | | `--env ` | Environment variable in KEY=VALUE form, set for every process of the computer; repeatable. | | `--headroom ` | Requested reservation for outstanding changes, such as 2Gi. | | `--idle-timeout ` | Requested time to keep execution after the last session ends: "never", or a nonnegative whole number followed by s, m, or h; the server validates the requested timeout. | | `--image ` | IDYL image the computer runs, by catalog name; 'idyl computer images' lists them. | | `--image-ref ` | Own OCI image the computer runs, used exactly as given; it must be pullable without credentials. | | `--memory ` | Memory limit of the computer, such as 512Mi or 4Gi, or "default" for the subnet's default. | | `--network-class ` | Network of the computer: internet, restricted-egress, none, or "default" for the subnet's default network. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--save-on-exec` | Save files when an exec ends; use =false to disable automatic saves. Default: `true`. | | `--save-window ` | Allowed failing-save time, such as 15m; the server applies policy caps. | | `--size ` | Requested on-disk size, such as 10Gi; the server applies storage policy. | | `--store ` | Admitted Store name; when omitted the server chooses the default. Fixed after creation. | #### Examples ```bash theme={null} # Create a computer on the subnet's default image idyl computer create payments # Create in another namespace and subnet idyl computer create payments --namespace production --subnet 550000000002 # Choose an IDYL image, size the computer, and set a variable idyl computer create payments --image python-3.12-ubuntu-24.04 --cpu 2 --memory 4Gi --env LOG_LEVEL=debug # Run an own image with no network idyl computer create payments --image-ref docker.io/library/debian:12 --network-class none # Keep its execution for an hour after its last session ends idyl computer create payments --idle-timeout 1h ``` ### `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 ```bash theme={null} idyl computer delete [flags] ``` #### Aliases * `rm` #### Flags | Flag | Description | | - | - | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--timeout ` | Maximum time to block with --wait; 0s checks the current state once. Default: `5m0s`. | | `--wait` | Block until the computer is finalized, exiting the way 'idyl wait' does. | | `-y, --yes` | Skip confirmation prompts. | #### Examples ```bash theme={null} # Delete a computer (with confirmation) idyl computer delete payments # Delete without confirmation idyl computer delete payments --yes # Delete and block until the computer is finalized idyl computer delete payments --yes --wait # Delete in another namespace and print the platform's answer as JSON idyl computer delete payments --namespace production --yes -o json ``` ### `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:\:\), 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 ```bash theme={null} idyl computer edit [flags] ``` #### Flags | Flag | Description | | - | - | | `--add-env ` | Set an environment variable in KEY=VALUE form, replacing one of the same name; repeatable. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--remove-env ` | Remove the environment variable of this name; repeatable. | | `--set-cpu ` | Set the computer's CPU limit, such as 500m or 2, or "default" for the subnet's default. | | `--set-egress-allow ` | Replace the allow list of a restricted-egress network with destinations: dns, or tcp:\:\; repeatable. | | `--set-headroom ` | Requested reservation for outstanding changes, such as 2Gi. | | `--set-idle-timeout ` | Requested time to keep execution after the last session ends: "never", or a nonnegative whole number followed by s, m, or h; the server validates the requested timeout. | | `--set-image ` | Replace the computer's image with an IDYL image, by catalog name; 'idyl computer images' lists them. | | `--set-image-ref ` | Replace the computer's image with an own OCI image, used exactly as given; it must be pullable without credentials. | | `--set-memory ` | Set the computer's memory limit, such as 512Mi or 4Gi, or "default" for the subnet's default. | | `--set-network-class ` | Replace the computer's network: internet, restricted-egress, none, or "default" for the subnet's default network. | | `--set-save-on-exec` | Save files when an exec ends; use =false to disable automatic saves. Default: `true`. | | `--set-save-window ` | Allowed failing-save time, such as 15m; the server applies policy caps. | | `--set-size ` | Requested on-disk size, such as 10Gi; the server applies storage policy. | #### Examples ```bash theme={null} # Keep execution for 15 minutes after the last session ends idyl computer edit payments --set-idle-timeout 15m # Never release execution for being idle idyl computer edit payments --set-idle-timeout never # Change the OS image idyl computer edit payments --set-image debian-12 # Give the computer more memory and return its CPU to the default idyl computer edit payments --set-memory 8Gi --set-cpu default # Set one variable and remove another idyl computer edit payments --add-env LOG_LEVEL=info --remove-env DEBUG # Allow only name resolution and one destination idyl computer edit payments --set-egress-allow dns --set-egress-allow tcp:443:pypi.org ``` ### `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 ```bash theme={null} idyl computer exec -- command [args...] [flags] ``` #### Flags | Flag | Description | | - | - | | `--detach-keys ` | Key sequence that detaches from a TTY session. Default: `ctrl-p,ctrl-q`. | | `-i, --interactive` | Keep stdin open for an interactive TTY session. | | `--interrupt` | Interrupt live Agent execution in an Actor's Computer first, discarding its unsaved work. | | `-t, --tty` | Allocate a TTY. | #### Examples ```bash theme={null} # Run a command in a computer idyl computer exec payments -- ls /workspace # Run an interactive shell with a TTY idyl computer exec -it payments -- /bin/sh ``` ### `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 \ and --rename \=\ 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 ```bash theme={null} idyl computer files [@version][:path] [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Opaque continuation value returned by the previous page. | | `--delete ` | Delete a saved path in the new version; repeat for more. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `--limit ` | Maximum entries in one page; the server chooses the default when omitted. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--rename ` | Rename a saved path in the new version, as from=to; repeat for more. | | `--save-first` | Save current files before listing; cannot be combined with @version. | #### Examples ```bash theme={null} idyl computer files payments idyl computer files payments@v2:assets -o json idyl computer files payments:logs --save-first idyl computer files payments --delete tmp --delete build/cache idyl computer files payments --rename notes.txt=docs/notes.txt ``` ### `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 ```bash theme={null} idyl computer fork @ [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl computer fork payments@v2 payments-copy idyl computer fork payments@before-cleanup experiment --idempotency-key experiment-fork -o json ``` ### `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 ```bash theme={null} idyl computer get [name] [flags] ``` #### Flags | Flag | Description | | - | - | | `-A, --all-namespaces` | List across every namespace in the account. | | `--limit ` | Maximum number of computers to list. Default: `20`. | | `--offset ` | Number of computers to skip. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--owner ` | Lifecycle owner to list: unowned, all, or an Actor ID. Default: `unowned`. | #### Examples ```bash theme={null} # List computers idyl computer get # List the subnet's computers across every namespace in the account idyl computer get -A # Include the computers Actors manage idyl computer get --owner all # Show one computer idyl computer get payments # Show it as JSON idyl computer get payments -o json ``` ### `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 ```bash theme={null} idyl computer go-back [version|version-name|entry-id] [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--undo` | Return to where the last go-back left. | #### Examples ```bash theme={null} idyl computer go-back payments v41 idyl computer go-back payments before-cleanup idyl computer go-back payments --undo ``` ### `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 ```bash theme={null} idyl computer history [entry-id] [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Show the page that starts where the previous page ended, from the value it reported. | | `--limit ` | Maximum number of entries to show, at most 200; the platform shows 50 when not given. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} # Show a computer's history idyl computer history payments # Show the next page idyl computer history payments --continue # Show one entry with its whole command idyl computer history payments 01954e20-7540-7ec4-93ec-14f783e6ab35 # Read the history as JSON idyl computer history payments -o json ``` ### `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 ```bash theme={null} idyl computer images [flags] ``` #### Flags | Flag | Description | | - | - | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} # List the images idyl computer images # Read the catalog as JSON idyl computer images -o json ``` ### `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 \, 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 ```bash theme={null} idyl computer list [flags] ``` #### Aliases * `ls` #### Flags | Flag | Description | | - | - | | `-A, --all-namespaces` | List across every namespace in the account. | | `--limit ` | Maximum number of computers to list. Default: `20`. | | `--offset ` | Number of computers to skip. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--owner ` | Lifecycle owner to list: unowned, all, or an Actor ID. Default: `unowned`. | #### Examples ```bash theme={null} # List computers idyl computer list # List the subnet's computers across every namespace in the account idyl computer list -A # Include the computers Actors manage, or select one Actor's computer idyl computer list --owner all idyl computer list --owner 01890a5d-ac96-774b-bcce-b302099a8057 # List as JSON idyl computer list -o json ``` ### `idyl computer restore` Publish a saved Computer version as a new version, preserving intervening history. Name a saved version as v2, or use its saved-version name. The command waits for publication; a running writer may apply it afterwards. 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 version selector after an uncertain response. When omitted, the CLI chooses a key and reports it if the wait is interrupted. Ctrl-C stops waiting without cancelling the recorded operation. #### Usage ```bash theme={null} idyl computer restore [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl computer restore payments v2 idyl computer restore payments before-cleanup -o json ``` ### `idyl computer ssh` Connect to a Computer in the resolved Namespace and subnet with the system OpenSSH client. The CLI probes the subnet's SSH endpoint, creates a short-lived one-use session, and launches OpenSSH with directly attached terminal streams once the session is ready. A dormant Computer is woken to serve the session; on a terminal, what the session waits for, such as the Computer waking or capacity to run it on, is written to stderr, and a session that cannot become ready is reported with its reason. With no command, the session is an interactive shell; a command after -- runs that command instead. The endpoint's host key is verified against the subnet's SSH host certificate authority. A session that is refused, or interrupted, before OpenSSH starts is cancelled. The CLI exits with OpenSSH's exit status, which is the remote command's when it ran. 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 ```bash theme={null} idyl computer ssh [-- command [args...]] [flags] ``` #### Flags | Flag | Description | | - | - | | `--interrupt` | Interrupt live Agent execution in an Actor's Computer first, discarding its unsaved work. | | `--port ` | Raw SSH port: auto, 22, or 443. Default: `auto`. | #### Examples ```bash theme={null} # Open a shell in a computer idyl computer ssh payments # Run one command idyl computer ssh payments -- uname -a # Connect through port 443 idyl computer ssh payments --port 443 ``` ### `idyl computer trash` List the branches of a Computer's history in Trash, each with its Trash ID, the branch, its entry and version counts, when it was moved to Trash, and when it is deleted forever. 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. \--restore \ brings a branch back, with its tip unchanged, and waits until it is back. --delete \ deletes a branch forever: its entries, versions, command output and every stored object only they reach are removed, and the command waits until the removal is complete. Delete forever cannot be undone and asks for confirmation unless --yes is given. \--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; \--restore prints the Trash entry and --delete the deletion. #### Usage ```bash theme={null} idyl computer trash [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Opaque continuation value returned by the previous page. | | `--delete ` | Delete the branch with this Trash ID forever. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `--limit ` | Maximum Trash entries in one page; the server chooses the default when omitted. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--restore ` | Restore the branch with this Trash ID. | | `-y, --yes` | Skip confirmation prompts. | #### Examples ```bash theme={null} idyl computer trash payments idyl computer trash payments --restore 019ad9ba-7334-7eca-9958-9f00c6c9fc01 idyl computer trash payments --delete 019ad9ba-7334-7eca-9958-9f00c6c9fc01 --yes ``` ### `idyl computer versions` List saved Computer versions, newest first. Version zero is the initial saved state. Version numbers are never reused. This command lists saved states; it does not save outstanding changes or change the current files. 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 v41=before-cleanup gives a version a name, replacing its previous name. \--unname v41 removes its name. A name must be unique within the Computer; the server judges names. Naming returns the updated version instead of a list. \--branch selects a branch by its ID from 'idyl computer branches'. --limit requests a page size, and --continue resumes a listing with the opaque value the previous page returned. JSON and YAML preserve the server's listing envelope, including its continue value. #### Usage ```bash theme={null} idyl computer versions [flags] ``` #### Flags | Flag | Description | | - | - | | `--branch ` | Branch whose saved versions to list. | | `--continue ` | Opaque continuation value returned by the previous page. | | `--limit ` | Maximum versions in one page; the server chooses the default when omitted. Default: `0`. | | `--name ` | Name a saved version, as v41=before-cleanup. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--unname ` | Remove a saved version's name, as v41. | #### Examples ```bash theme={null} idyl computer versions payments idyl computer versions payments --continue -o json idyl computer versions payments --name v41=before-cleanup idyl computer versions payments --unname v41 ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.