[GH-ISSUE #599] return value

kerem commented

2026-03-15 11:01:13 +03:00

Owner

Originally created by @charliez0 on GitHub (Dec 27, 2023).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/599

Describe the bug
A clear and concise description of what the bug is.
When the program triggered by asciinema exit with non-zero value, asciinema returns zero
To Reproduce

root@speedtest:~# asciinema rec -c "exit 1" test.rec
asciinema: recording asciicast to test.rec
asciinema: exit opened program when you're done
asciinema: recording finished
asciinema: asciicast saved to test.rec
root@speedtest:~# echo $?
0

Expected behavior
return non-zero when triggered program exit code non-zero
Versions:

root@speedtest:~# cat /etc/os-release
PRETTY_NAME="Ubuntu Noble Numbat (development branch)"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04 (Noble Numbat)"
VERSION_CODENAME=noble
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=noble
LOGO=ubuntu-logo
root@speedtest:~# asciinema --version
asciinema 2.4.0

Additional context
Add any other context about the problem here.

Originally created by @charliez0 on GitHub (Dec 27, 2023). Original GitHub issue: https://github.com/asciinema/asciinema/issues/599 **Describe the bug** A clear and concise description of what the bug is. When the program triggered by asciinema exit with non-zero value, asciinema returns zero **To Reproduce** ```plain root@speedtest:~# asciinema rec -c "exit 1" test.rec asciinema: recording asciicast to test.rec asciinema: exit opened program when you're done asciinema: recording finished asciinema: asciicast saved to test.rec root@speedtest:~# echo $? 0 ``` **Expected behavior** return non-zero when triggered program exit code non-zero **Versions:** ```plain root@speedtest:~# cat /etc/os-release PRETTY_NAME="Ubuntu Noble Numbat (development branch)" NAME="Ubuntu" VERSION_ID="24.04" VERSION="24.04 (Noble Numbat)" VERSION_CODENAME=noble ID=ubuntu ID_LIKE=debian HOME_URL="https://www.ubuntu.com/" SUPPORT_URL="https://help.ubuntu.com/" BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" UBUNTU_CODENAME=noble LOGO=ubuntu-logo root@speedtest:~# asciinema --version asciinema 2.4.0 ``` **Additional context** Add any other context about the problem here.

kerem closed this issue

2026-03-15 11:01:18 +03:00

kerem commented

2026-03-15 11:01:24 +03:00

Author

Owner

@ku1ik commented on GitHub (Jan 8, 2024):

Given asciinema itself finished without errors, finished recording successfully, I think the current behaviour is not too bad. But it really depends on what one expects here.

What do you think of an option, e.g. --return or similar, to exit with the code returned by the recorded program? script command (which asciinema was inspired by) does it via -e / --return for example.

@ku1ik commented on GitHub (Jan 8, 2024): Given asciinema itself finished without errors, finished recording successfully, I think the current behaviour is not too bad. But it really depends on what one expects here. What do you think of an option, e.g. `--return` or similar, to exit with the code returned by the recorded program? `script` command (which asciinema was inspired by) does it via `-e / --return` for example.

kerem commented

2026-03-15 11:01:29 +03:00

Author

Owner

@charliez0 commented on GitHub (Jan 16, 2024):

Yes, it would be great to add one option so that no breaking changes would made to fix this

@charliez0 commented on GitHub (Jan 16, 2024): Yes, it would be great to add one option so that no breaking changes would made to fix this

kerem commented

2026-03-15 11:01:34 +03:00

Author

Owner

@moritzdietz commented on GitHub (Jan 18, 2024):

I know that some cli tools have an option to "transfer" exit codes depending on what happens inside of the application.
jq for example has the option --exit-status

Sets the exit status of jq to 0 if the last output value was neither false nor null, 1 if the last output value was either false or null, or 4 if no valid result was ever produced. Normally jq exits with 2 if there was any usage problem or system error, 3 if there was a jq program compile error, or 0 if the jq program ran.

https://jqlang.github.io/jq/manual/

Another example is curl with their --fail argument:

-f, --fail
(HTTP) Fail silently (no output at all) on server errors. This is mostly done to enable scripts etc to better deal with failed attempts. In normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22.

This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407).

Example:
curl --fail https://example.com

See also --fail-with-body.

I can see the appeal for CI stuff maybe?!

@moritzdietz commented on GitHub (Jan 18, 2024): I know that some cli tools have an option to "transfer" exit codes depending on what happens inside of the application. `jq` for example has the option `--exit-status` >Sets the exit status of jq to 0 if the last output value was neither false nor null, 1 if the last output value was either false or null, or 4 if no valid result was ever produced. Normally jq exits with 2 if there was any usage problem or system error, 3 if there was a jq program compile error, or 0 if the jq program ran. https://jqlang.github.io/jq/manual/ Another example is curl with their `--fail` argument: > -f, --fail (HTTP) Fail silently (no output at all) on server errors. This is mostly done to enable scripts etc to better deal with failed attempts. In normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22. > > This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407). > > Example: curl --fail https://example.com > > See also --fail-with-body. I can see the appeal for CI stuff maybe?!

kerem commented

2026-03-15 11:01:39 +03:00

Author

Owner

@ku1ik commented on GitHub (Jan 18, 2024):

Many good ideas there, thanks.

I see 2 options:

a) forward exit code from the recorded shell/command as is (like script does),
b) use specific exit codes for different failure scenarios (like jq)

I'm leaning towards a) but I'm open to all ideas.

@ku1ik commented on GitHub (Jan 18, 2024): Many good ideas there, thanks. I see 2 options: a) forward exit code from the recorded shell/command as is (like script does), b) use specific exit codes for different failure scenarios (like jq) I'm leaning towards a) but I'm open to all ideas.

kerem commented

2026-03-15 11:01:44 +03:00

Author

Owner

@moritzdietz commented on GitHub (Jan 18, 2024):

I really like option a.) as well!

@moritzdietz commented on GitHub (Jan 18, 2024): I really like option a.) as well!

kerem commented

2026-03-15 11:01:49 +03:00

Author

Owner

@balupton commented on GitHub (Jan 24, 2025):

The standardised term for them is exit status:

As for this feature request, what specifically is the use case that warrants it? I had thought about exit statuses myself for my own use case.

As for the implementation of exit status, there seems to various rolls exit status can play in asciinema.

recording of the exit status inside the cast files, what I would want
have asciinema rec return the exit status it encountered while returning, what the OP in this thread seems to be about
have asciinema play return the exit status it recorded in the cast files, optional

For me, the first request here, the recording of exit statuses is the important part, and it seems that is not currently done:

> asciinema rec --command 'exit 5' . 
::: Recording session started, writing to ./2025-01-24-14-31-23-93538.cast
::: Recording session ended

> cat 2025-01-24-14-31-23-93538.cast 
{"version":2,"width":264,"height":39,"timestamp":1737700283,"command":"exit 5","env":{"TERM":"xterm-256color","SHELL":"/opt/homebrew/bin/fish"},"theme":{"fg":"#ffffff","bg":"#1e1e1e","palette":"#000000:#990000:#00a600:#999900:#0000b3:#b300b3:#00a6b3:#bfbfbf:#666666:#e60000:#00d900:#e6e600:#0000ff:#e600e6:#00e6e6:#e6e6e6"}}

Having exit statuses being recorded will allow me to use asciinema and its cast files to automatically test and verify experiences remain consistent across my own CLI iterations, while at the same time having recording of expected experiences for publicity and documentation.

If the second or third request in implemented, then I would expect asciinema to return an appropriate exit status for when an error occurs within asciinema's recording or playback of the cast file, perhaps 132 would be a contender:

4. SIGILL (Illegal instruction signal. Sent to a process when it attempts to execute an illegal or privileged instruction.) [Exit Status: 128 + 4 = 132]

Taken from https://github.com/bevry/dorothy/blob/master/docs/bash/errors.md which documents various standardised exit statuses.

@balupton commented on GitHub (Jan 24, 2025): The standardised term for them is exit status: - https://en.wikipedia.org/wiki/Exit_status - https://www.gnu.org/software/bash/manual/html_node/Exit-Status.html - https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html As for this feature request, what specifically is the use case that warrants it? I had thought about exit statuses myself for [my own use case](https://discourse.asciinema.org/t/using-asciinema-for-testing/923/1). As for the implementation of exit status, there seems to various rolls exit status can play in asciinema. 1. [ ] recording of the exit status inside the cast files, what I would want 1. [ ] have `asciinema rec` return the exit status it encountered while returning, what the OP in this thread seems to be about 1. [ ] have `asciinema play` return the exit status it recorded in the cast files, optional For me, the first request here, the recording of exit statuses is the important part, and it seems that is not currently done: ``` > asciinema rec --command 'exit 5' . ::: Recording session started, writing to ./2025-01-24-14-31-23-93538.cast ::: Recording session ended > cat 2025-01-24-14-31-23-93538.cast {"version":2,"width":264,"height":39,"timestamp":1737700283,"command":"exit 5","env":{"TERM":"xterm-256color","SHELL":"/opt/homebrew/bin/fish"},"theme":{"fg":"#ffffff","bg":"#1e1e1e","palette":"#000000:#990000:#00a600:#999900:#0000b3:#b300b3:#00a6b3:#bfbfbf:#666666:#e60000:#00d900:#e6e600:#0000ff:#e600e6:#00e6e6:#e6e6e6"}} ``` Having exit statuses being recorded will allow me to use asciinema and its cast files to automatically test and verify experiences remain consistent across my own CLI iterations, while at the same time having recording of expected experiences for publicity and documentation. If the second or third request in implemented, then I would expect asciinema to return an appropriate exit status for when an error occurs within asciinema's recording or playback of the cast file, perhaps `132` would be a contender: ``` 4. SIGILL (Illegal instruction signal. Sent to a process when it attempts to execute an illegal or privileged instruction.) [Exit Status: 128 + 4 = 132] ``` Taken from https://github.com/bevry/dorothy/blob/master/docs/bash/errors.md which documents various standardised exit statuses.

kerem commented

2026-03-15 11:01:55 +03:00

Author

Owner

@ku1ik commented on GitHub (May 31, 2025):

2 things just landed in develop:

new --return option for rec, stream and session commands - propagates session exit status
exit status is now saved as "x" event as the final event in asciicast (v3) files

@ku1ik commented on GitHub (May 31, 2025): 2 things just landed in `develop`: - new `--return` option for `rec`, `stream` and `session` commands - propagates session exit status - exit status is now saved as "x" event as the final event in asciicast (v3) files

Rows
Columns

[GH-ISSUE #599] return value #928