API

This is a complete listing of all of the API functions that cy provides in the top-level Janet environment (ie you do not need to import or use anything.)

Janet code executed with cy can also access everything from Janet's standard library except for anything in spork. In addition, Janet's ev family of functions probably will not work; I have never tested them.

Concepts

Binding

Several API functions related to binding keys return a Binding. A Binding table represents a single key sequence and its associated function. Each table has the following properties:

:node: the NodeID where the binding is defined.
:sequence: a list of strings representing the key sequence that will execute this action. If the original call to key/bind used a regex, it will be returned as a string with a re: prefix.
:function: the Janet function that will be called when this sequence is executed.

For example:

{
  :node 1
  :sequence ["ctrl+a" "t"]
  :function <some function>
}

Color

Some API functions, such as style/render, accept colors as input. cy supports True Color colors specified in hexadecimal along with ANSI 16 and ANSI-256 colors. Under the hood, cy uses charmbracelet/lipgloss and thus supports its color references.

You can read more about color support in terminal emulators here.

Examples of valid colors:

"#ffffff" # true color
"#123456" # true color
"255" # ANSI 256
"0" # ANSI 16

Color map

A color map is a mapping from one color to another. They can represented by Janet structs or tables:

# The "zenburn" color map
# This maps the default 16 ANSI colors to hand-picked RGB colors
@{"0" "#383838"
  "1" "#dca3a3"
  "2" "#5f7f5f"
  "3" "#e0cf9f"
  "4" "#7cb8bb"
  "5" "#dc8cc3"
  "6" "#93e0e3"
  "7" "#dcdccc"
  "8" "#6f6f6f"
  "9" "#dfaf8f"
  "10" "#404040"
  "11" "#606060"
  "12" "#808080"
  "13" "#c0c0c0"
  "14" "#000000"
  "15" "#ffffff"}

For more information about color maps, see the relevant section in the parameters chapter.

Command

cmd/query and {{api/commands}} return Commands, which are structs that look like this:

{:text "echo 'Hello, World!'" # The command that was run
 :directory "/some/dir"
 # When the command started executing
 :executed-at {} # Time
 # When it finished
 :completed-at {} # Time
 # These three properties only have internal meaning for now
 :prompted 23
 :executed 26
 :completed 52
 :pending false
 # Input and output are Selections, which can currently only be passed to
 # input/find previews. Refer to the standard library.
 :input @[{:from (97 6)
           :to (97 7)}]
 :output {:from (98 0)
          :to (98 42)}}

NodeID

Many API functions have a parameter of type NodeID, which can be one of two values:

:root which is a short way of referring to cy's top-level group.
An integer that refers to a node in cy's node tree. You cannot infer these yourself, but they are returned from API functions like pane/current and group/children.

Time

The (time/*) family of functions works with Time values, which are similar (but not identical) to the value returned by Janet's built-in (os/date) function.

Time values are structs with the following properties:

{:dst false # unused, just to mimic (os/date)
 :hours 10
 :milliseconds 624
 :minutes 15
 :month 9
 :month-day 15
 :seconds 31
 :utc false # if false, properties are in local time
 :week-day 0
 :year 2024
 :year-day 259}

For specifics on the range of each scalar property, consult the documentation for Go's time package, such as for time.Weekday().

Symbols

action/add-node action/browse-animations action/choose-frame action/clear-layout action/command-palette action/cpu-profile action/ctrl-r action/detach action/jump-command action/jump-group-pane action/jump-history-command action/jump-pane action/jump-pane-command action/jump-project action/jump-screen-lines action/jump-shell action/kill-and-reattach action/kill-layout-pane action/kill-pane action/kill-server action/margins-160 action/margins-80 action/margins-bigger action/margins-smaller action/move-down action/move-left action/move-right action/move-up action/new-project action/new-shell action/new-tab action/next-pane action/next-tab action/open-log action/open-replay action/paste action/paste-clipboard action/prev-pane action/prev-tab action/random-frame action/recall-command action/reload-config action/remove-layout-pane action/remove-parent action/rename-pane action/rename-tab action/replay-playback-1x action/replay-playback-2x action/replay-playback-5x action/replay-playback-reverse-1x action/replay-playback-reverse-2x action/replay-playback-reverse-5x action/search-borg action/set-borders-title action/set-borders-title-bottom action/set-layout-borders action/set-pane-colors action/show-color-map action/split-down action/split-left action/split-right action/split-up action/toggle-margins action/trace assoc clipboard/get clipboard/set cmd/commands cmd/kill cmd/new cmd/path cmd/query color-maps/get color-maps/get-all color-maps/get-id color-maps/set cy/cpu-profile cy/detach cy/kill-server cy/paste cy/reload-config cy/trace exec/file group/children group/leaves group/mkdir group/new input/find input/text key/action key/bind key/bind-many key/bind-many-tag key/current key/get key/get-actions key/remap key/unbind layout/assoc layout/attach layout/attach-first layout/attach-id layout/attach-path layout/attached? layout/bar layout/borders layout/color-map layout/detach layout/find layout/find-last layout/get layout/has? layout/hsplit layout/map layout/margins layout/move layout/move-down layout/move-left layout/move-right layout/move-up layout/new layout/pane layout/pane? layout/path layout/remove-attached layout/replace layout/replace-attached layout/set layout/split layout/split-down layout/split-left layout/split-right layout/split-up layout/successors layout/tab layout/tabs layout/type? layout/vsplit msg/log msg/toast pane/attach pane/current pane/history-backward pane/history-forward pane/screen pane/send-keys param/get param/rset param/set param/set-many path/abs path/base path/glob path/join register/get register/insert register/set replay/beginning replay/big-word-backward replay/big-word-end-backward replay/big-word-end-forward replay/big-word-forward replay/command-backward replay/command-forward replay/command-select-backward replay/command-select-forward replay/copy replay/copy-clipboard replay/copy-default replay/cursor-down replay/cursor-left replay/cursor-right replay/cursor-up replay/end replay/end-of-line replay/end-of-screen-line replay/first-non-blank replay/first-non-blank-screen replay/half-page-down replay/half-page-up replay/jump-again replay/jump-backward replay/jump-forward replay/jump-reverse replay/jump-to-backward replay/jump-to-forward replay/last-non-blank replay/last-non-blank-screen replay/middle-of-line replay/middle-of-screen-line replay/open replay/open-file replay/quit replay/scroll-down replay/scroll-up replay/search-again replay/search-backward replay/search-forward replay/search-reverse replay/select replay/start-of-line replay/start-of-screen-line replay/swap-screen replay/time-play replay/time-playback-rate replay/time-step-back replay/time-step-forward replay/word-backward replay/word-end-backward replay/word-end-forward replay/word-forward search/cancel search/first search/focus-input search/last search/new search/next search/prev shell/attach shell/new style/render style/text time/format time/now tree/group? tree/name tree/pane? tree/parent tree/path tree/rm tree/root tree/set-name viewport/get-animations viewport/get-frames viewport/set-frame

action/add-node

function

(action/add-node)

Add a node to the layout.

cy documentation