SEXPECT(1)

📦 version 2.3.15, in alpine 3.24

🎀 SEXPECT(1) — Expect for Shells 🎀

okay so bestie, <pink>sexpect is literally Expect for Shells — yes, that is the whole NAME vibe. It’s the tool you reach for when you want Expect-style automation but you’re living that shell-script life (sh, bash, ksh, zsh, ...). 🐚✨

🌸 SYNOPSIS 🌸

sexpect [OPTION] SUB-COMMAND [OPTION]

🦋 DESCRIPTION 🦋

sexpect is another implementation of Expect, and it’s specifically designed for Shell scripts (sh, bash, ksh, zsh, ...). 💅

sexpect is designed in the client/server model. sexpect spawn starts the server (running as a daemon) and runs the specified PROGRAM in background. Other sexpect sub-commands (send, expect, wait, ...) communicate to the server as client commands. 🫶

🌈 GLOBAL OPTIONS 🌈

  • -debug | -d — Debug mode. The server (sexpect spawn) will run in foreground and more information will be displayed. 🔍
  • -help | --help | -h — Show brief sexpect help. 🆘
  • -sock SOCKFILE | -s SOCKFILE — The socket file used for client/server communication. This option is required for most sub-commands. 🔌

You can save the SOCKFILE in the SEXPECT_SOCKFILE environment variable so you don’t need to specify the -sock option for each command. For example:

export SEXPECT_SOCKFILE=~/.sexpect-bash.sock
sexpect spawn bash --norc
... ...

The socket file will be automatically created if it does not exist. ✨

  • -version | --version — Show sexpect version. 🏷️

👑 SUB-COMMANDS 👑

Sub-commands may have aliases. For example, sexpect spawn can also be written as sexpect sp or sexpect fork. For each sub-command, the supported aliases are listed in parentheses. iykyk 💫

🐣 spawn (sp, fork)

sexpect spawn [OPTION] PROGRAM [ARGS]

The spawn sub-command will first make itself run as a background server. Then the server will start the specified PROGRAM on a new allocated pty. 🖥️✨

The spawn sub-command supports the following options:

  • -append — See option -logfile. 📎
  • -autowait | -nowait — Turn on the autowait flag which by default is off. See sub-command set for more information. ⏳
  • -close-on-exit | -cloexit — Close the pty after the spawned process has exited even if the spawned process’s child processes are still opening the pty. (Example: ssh -f) 🚪
  • -nonblock | -nb — Turn on the nonblock flag which by default is off. See sub-command set for more information. 🚦
  • -idle-close N | -idle N — The background server process will close the PTY and exit if there are no client requests in the last N seconds. Closing the PTY would usually cause the spawned process to receive SIGHUP and be killed. 💀
  • -logfile FILE | -logf FILE | -log FILE — All output from the spawned process will be copied to the specified FILE. By default the FILE will be overwritten. Use -append if you want to append to it. 📝
  • -nohup — Make the spawned process ignore SIGHUP. (Example: ssh -f) 🙅‍♀️
  • -term TERM | -T TERM — Set the environment variable TERM for the spawned process. This is useful when the TERM variable is not set (for example for jobs started by cron/crond or atd). 🌡️
  • -timeout N | -t N — Set the default timeout for sexpect expect. A negative value means no timeout. The default value is -1. ⏰
  • -ttl N — The background server process will close the PTY and exit N seconds after the process is spawned. Usually this would cause the process to receive SIGHUP and be killed. ⌛
  • -zombie-idle N | -z N — When the spawned process closes the pty and exits, if there are no client requests in the last N seconds the server will automatically wait the spawned process and then exit. This helps avoid too many zombie processes running around. The default value is 86400 (24 hours). Use -1 to disable this. 🧟

Exit status: 0 will be returned if the background server has successfully started. This does not necessarily mean the PROGRAM has been successfully spawned (e.g. if the specified PROGRAM cannot be found). Non-zero will be returned if the server fails to start for some reason. ✅❌

🔍 expect (exp, ex, x)

sexpect expect [OPTION] [ <[-exact] | -glob | -re> PATTERN] [-eof]

If the PATTERN is specified, it’ll wait until the PATTERN matches the output of the spawned process. If -eof is specified, it’ll wait until EOF (end-of-file) is seen. If neither PATTERN nor -eof is specified, then it defaults to:

expect -timeout 0 -re '.*'

The expect sub-command supports the following options:

  • -anchor-newline | -anchor — Used with -re PATTERN. Compile the PATTERN for newline-sensitive matching by passing the REG_NEWLINE flag to regcomp(3). By default, newline is a completely ordinary character with no special meaning. With this flag, bracket expressions [^...] and . never match newline, a ^ anchor matches the null string after any newline in the string in addition to its normal function, and the $ anchor matches the null string before any newline in the string in addition to its normal function. 🧵
  • -cstring | -cstr | -c — C style backslash escapes would be recognized and replaced in PATTERN. See sub-command send for the list of supported backslash escapes. 🪄
  • -eof — Wait until EOF is seen from the spawned process. 🛑
Note that receiving EOF from the process does not necessarily mean the process has exited. 😭
  • -exact PATTERN | -ex PATTERN — Match the PATTERN as an “exact” string. 🎯
  • -glob PATTERN | -gl PATTERN — Match the PATTERN as a glob style pattern. For convenience, the glob patterns also support ^ and $ which match the beginning and end of data currently in the internal matching buffer. 🌟
  • -lookback N | -lb N — Show the most recent last N lines of output so you’d know where you were last time. 🕰️
  • -nocase | -icase | -i — Ignore case when matching PATTERN. Used with -exact, -glob or -re. 🔠
  • -re PATTERN — Match the PATTERN as an extended regular expression (ERE). 🧠
  • -timeout N | -t N — Override the default expect timeout (see spawn -timeout). ⏱️

Exit status: 0 will be returned if the match succeeds before timeout or EOF. 💖

If the command fails, the chkerr sub-command can be used to check if the failure is caused by EOF or TIMEOUT. For example (in Bash):

sexpect expect -re foobar
ret=$?
if [[ $ret == 0 ]]; then
    # Cool we got the expected output
elif sexpect chkerr -errno $ret -is eof; then
    # EOF from the spawned process (most probably dead)
elif sexpect chkerr -errno $ret -is timeout; then
    # Timed out waiting for the expected output
else
    # Other errors
fi

📤 send (s)

sexpect send [OPTION] [ [--] STRING | -file FILE | -env NAME]

The send sub-command sends data to the spawned process. 📨

Note that the data to be sent must be less than 1024 bytes. To send more data, use multiple sexpect send commands. 😌

The send sub-command supports the following options:

  • -cstring | -cstr | -c — C language style backslash escapes would be recognized and replaced in STRING before sending to the spawned process. 🪄

The following standard C language escapes are supported:

\\ \a \b \f \n \r \t \v
\xHH \xH
\ooo \oo \o

Other supported escapes:

\e \E : ESC, the escape char.
\cX   : CTRL-X, e.g. \cc will be converted to the CTRL-C char.
  • -enter | -cr — Append ENTER (\r) to the specified STRING before sending to the spawned process. ↩️
  • -fd FD — Read data from file descriptor FD and send to the spawned process. Option -limit must be specified with -fd. Use -strip to remove trailing white space chars. 📥
  • -file FILE | -f FILE — Send the content of the FILE to the spawned process. If FILE is - then stdin will be used. Option -limit must be specified if FILE is not a regular file. Use -strip to remove trailing white space chars. 📄
  • -env NAME | -var NAME — Send the value of environment variable NAME to the spawned process. 🌱
  • -limit LIMIT — Used with -file or -fd. Read at most LIMIT chars from the file. LIMIT should be in range [1, 1024]. 🔢
  • -strip — See option -file. 🧼

🎮 interact (i)

sexpect interact [OPTION]

The interact sub-command is used to attach to the spawned process and manually interact with it. To detach from the process, press CTRL+] (CTRL-]). 🕹️

interact would fail if it’s not running on a tty/pty. 😬

If the spawned process exits when you’re interacting with it then interact will exit with the same exit code of the spawned process and you don’t need to call the wait sub-command any more. And the background server will also exit. 👋

The interact sub-command supports the following options:

  • -lookback N | -lb N — Show the most recent last N lines of output after attaching to the process so you’d know where you were last time. 🕰️
  • -nodetach | -nodet — Disable CTRL-]. This may be useful in scripts. 🔒
  • -re PATTERN — Automatically detach from the spawned process when the output matches the RE pattern. After a successful match, you can use expect_out to get substring matches. 🎯
  • <-subst | -sub> PATTERN::REPLACE — Dynamically monitor output from the spawned process and if the output matches the PATTERN then change the matching part to REPLACE. 🔁

REPLACE can include (0), (1), (2), ..., (9) for RE match groups. (0) is for the whole match and (1) .. (9) for corresponding subgroups. For example, -subst "(foo)(bar)::(0)-(1)-(2)" would change "foobar" to "foobar-foo-bar". ✨

The PATTERN cannot include "::". 🚫

At most 10 -subst options can be specified. 🔟

  • -cstring | -cstr | -c — Used with -re PATTERN or -subst PATTERN::REPLACE. C style backslash escapes would be recognized and replaced in PATTERN or REPLACE. See sub-command send for the list of supported backslash escapes. 🪄
  • -nocase | -icase | -i — Used with -re PATTERN or -subst PATTERN::REPLACE. Ignore case when matching PATTERN. 🔠
  • -anchor-newline | -anchor — Used with -re PATTERN or -subst PATTERN::REPLACE. See sub-command expect for more details.. 🧵

⏳ wait (w)

sexpect wait

The wait sub-command waits for the spawned process to complete and return the spawned process' exit code. 🫶

expect_out (expout, out) 🎀

okay bestie, so picture this: your expect sub-command just successfully matched the PATTERN you gave it, and now you want the substring matches? That’s literally what expect_out is for. ✨

sexpect expect_out [< -index | -i> INDEX]

The server side saves up to 9 (1-9) RE substring matches. 0 refers to the string that matched the whole PATTERN. If you don’t pass INDEX, it defaults to 0. No cap. 💅

Example: if this command

sexpect expect -re 'a(bc)d(ef)g'

succeeds (exits 0), then these commands

sexpect expect_out -index 0
sexpect expect_out -index 1
sexpect expect_out -index 2

would output abcdefg, bc, and ef, respectively. Slay. 💖

chkerr (chk, ck) 🩺

If the previous expect sub-command fails, chkerr checks whether the failure is caused by EOF or TIMEOUT. See the expect sub-command for an example.

sexpect chkerr -errno NUM -is REASON

Options:

  • -errno NUM, -err NUM — NUM is the exit code of the previous failed expect sub-command.
  • -is REASON — REASON can be eof, timeout.

Exit status: 0 will be returned if the specified error NUM is caused by the REASON. 1 will be returned if the specified error NUM is NOT caused by the REASON. It’s giving error vibe check. 👀

close (c) 🚪

sexpect close

The close sub-command closes the spawned process’s pty by force. This would usually cause the process to receive SIGHUP and be killed. dramatic but effective. 💀

kill (k) ⚡

sexpect kill [-SIGNAME | -SIGNUM]

The kill sub-command sends the specified signal to the spawned process. The default signal is SIGTERM.

Options:

  • -SIGNAME — Specify the signal with name. Only the following signal names are supported:
SIGCONT SIGHUP  SIGINT  SIGKILL SIGQUIT
SIGSTOP SIGTERM SIGUSR1 SIGUSR2

SIGNAME is case insensitive and the prefix SIG is optional. iykyk 🫶

  • -SIGNUM — Specify the signal with number.

set ⚙️

sexpect set [OPTION]

The set sub-command can be used to dynamically change server side’s parameters after spawn. Lowkey powerful. 🔥

Options:

  • -autowait FLAG, -nowait FLAG — FLAG can be 0, 1, on, off.

By default, after the spawned process exits, the server side will wait for the client to call wait to get the exit status of the process and then the server will exit. When autowait is turned on, after the spawned process exits it’ll be automatically waited and then the server will exit.

  • -nonblock FLAG, -nb FLAG — FLAG can be 0, 1, on, off.

By default, the spawned process will be blocked if it outputs too much and the client (either expect, interact or wait) does not read the output in time. When nonblock is turned on, the output from the process will not be blocked so the process can continue running.

  • -idle-close N, -idle N — Set the IDLE value. See the spawn sub-command for details.
  • -timeout N, -t N — See the spawn sub-command for details.
  • -ttl N — See the spawn sub-command for details.

get 🔍

sexpect get [OPTION]

Retrieve server side information.

Options:

  • -all, -a — Get all available information from server side.
  • -autowait, -nowait — Get the autowait flag.
  • -nonblock, -nb — Get the nonblock flag.
  • -idle-close, -idle — Get the IDLE value. See spawn for details.
  • -pid — Get the spawned process’s PID.
  • -ppid — Get the spawned process’s PPID.
  • -tty, -pty, -pts — Get the spawned process’s tty.
  • -timeout, -t — Get the current default timeout value.
  • -ttl — Get the TTL value. See spawn for details.
  • -expect-buf N, -expbuf N — Dump the most recent N (at most 4096) chars from the internal expect buffer.

🌱 ENVIRONMENT VARIABLES 🌱

  • SEXPECT_SOCKFILE — See GLOBAL OPTIONS for details. your env var bestie is important ✨

🔗 RESOURCES 🔗

Project home: https://github.com/clarkwang/sexpect/

👀 SEE ALSO 👀

expect(1), pty(7), pts(4), glob(3), fnmatch(3)

👑 AUTHOR 👑

Written by Clark Wang <dearvoid AT gmail.com>.

🐛 REPORTING BUGS 🐛

Report bugs to Clark Wang <dearvoid AT gmail.com> or open an issue at https://github.com/clarkwang/sexpect/issues/

This page is serving sexpect 2.3.14 realness, dated 2022-09-16 — periodt, bestie. 💖✨

📦 where this page comes from