Mirrors/asciinema
1
0
Fork 0
mirror of https://github.com/asciinema/asciinema.git synced 2025-12-16 03:38:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improve --help messages

Browse Source
This commit is contained in:
Marcin Kulik
2025-06-19 13:32:12 +02:00
parent 049fc683df
commit 9b8b26e6a9
1 changed files with 293 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
src/cli.rs
View File

@@ -14,36 +14,86 @@ pub struct Cli {
#[command(subcommand)]
pub command: Commands,
/// Quiet mode - suppress diagnostic messages
#[clap(short, long, global = true, display_order = 101)]
/// Suppress diagnostic messages and progress indicators. When enabled, asciinema will run silently and only display error messages if something goes wrong.
#[clap(
short,
long,
global = true,
display_order = 101,
help = "Quiet mode - suppress diagnostic messages",
long_help
)]
pub quiet: bool,
}
#[derive(Debug, Subcommand)]
pub enum Commands {
/// Record a terminal session
#[clap(visible_alias = "rec")]
/// Record a terminal session to a file.
///
/// Captures all terminal output and optionally keyboard input, saving it for later playback. Supports various output formats, idle time limiting, and session customization options.
///
/// Press <ctrl+d> or type 'exit' to end the recording session.
/// Press <ctrl+\> to pause/resume capture of the session.
#[clap(visible_alias = "rec", about = "Record a terminal session", long_about)]
Record(Record),
/// Stream a terminal session
/// Stream a terminal session in real-time.
///
/// Broadcasts your terminal session live via either a local HTTP server (for local/LAN viewing) or a remote asciinema server (for public sharing). Viewers can watch your session as it happens through a web interface.
///
/// Press <ctrl+d> or type 'exit' to end the streaming session.
/// Press <ctrl+\> to pause/resume capture of the session.
#[clap(about = "Stream a terminal session", long_about)]
Stream(Stream),
/// Record and stream a terminal session
/// Record and stream a terminal session simultaneously.
///
/// Combines the functionality of record and stream commands, allowing you to save a recording to a file while also broadcasting it live to viewers.
///
/// Press <ctrl+d> or type 'exit' to end the session.
/// Press <ctrl+\> to pause/resume capture of the session.
#[clap(about = "Record and stream a terminal session", long_about)]
Session(Session),
/// Play back a terminal session
/// Play back a recorded terminal session.
///
/// Displays a previously recorded asciicast file in your terminal with various playback controls (see below). Supports local files and remote URLs.
///
/// Press <ctrl+c> to interrupt the playback.
/// Press <space> to pause/resume.
/// Press '.' to step forward (while paused).
/// Press ']' to skip to the next marker (while paused).
#[clap(about = "Play back a terminal session", long_about)]
Play(Play),
/// Upload a recording to an asciinema server
/// Upload a recording to an asciinema server.
///
/// Takes a local asciicast file and uploads it to an asciinema server (either asciinema.org or a self-hosted server) where it can be shared publicly via a URL.
#[clap(about = "Upload a recording to an asciinema server", long_about)]
Upload(Upload),
/// Authenticate this CLI with an asciinema server account
/// Authenticate with an asciinema server.
///
/// Creates a user account link between your local CLI and an asciinema server account. Optional for uploading with the upload command, required for remote streaming with the stream and session commands.
#[clap(
about = "Authenticate this CLI with an asciinema server account",
long_about
)]
Auth(Auth),
/// Concatenate multiple recordings
/// Concatenate multiple recordings into one.
///
/// Combines two or more asciicast files in sequence, adjusting timing so each recording plays immediately after the previous one ends. Useful for creating longer recordings from multiple shorter sessions.
///
/// Note: in asciinema 2.x this command used to print raw terminal output for a given session
/// file. If you're looking for this behavior then use `asciinema convert -f raw <FILE> -` instead.
#[clap(about = "Concatenate multiple recordings", long_about)]
Cat(Cat),
/// Convert a recording to another format
/// Convert a recording to another format.
///
/// Transform asciicast files between different formats (v1, v2, v3) or export to other formats like raw terminal output or plain text. Supports reading from files, URLs, or stdin and writing to files or stdout.
#[clap(about = "Convert a recording to another format", long_about)]
Convert(Convert),
}
@@ -52,48 +102,86 @@ pub struct Record {
/// Output file path
pub file: String,
/// Output file format [default: asciicast-v3]
#[arg(short = 'f', long, value_enum, value_name = "FORMAT")]
/// Specify the format for the output file. The default is asciicast-v3. If the file path ends with .txt, the txt format will be selected automatically unless --output-format is explicitly specified.
#[arg(
short = 'f',
long,
value_enum,
value_name = "FORMAT",
help = "Output file format [default: asciicast-v3]",
long_help
)]
pub output_format: Option<Format>,
/// Command to start in the session [default: $SHELL]
#[arg(short, long)]
/// Specify the command to execute in the recording session. If not provided, asciinema will use your default shell from the $SHELL environment variable. This can be any command with arguments, for example: --command "python script.py" or --command "bash -l". Can also be set via config file option recording.command.
#[arg(
short,
long,
help = "Command to start in the session [default: $SHELL]",
long_help
)]
pub command: Option<String>,
/// Enable input (keyboard) recording
#[arg(long, short = 'I', alias = "stdin")]
/// Enable recording of keyboard input in addition to terminal output. When enabled, both what you type and what appears on the screen will be captured. Note that sensitive input like passwords will also be recorded when this option is enabled. Can also be set via the config file option recording.rec_input.
#[arg(
long,
short = 'I',
alias = "stdin",
help = "Enable input (keyboard) recording",
long_help
)]
pub rec_input: bool,
/// Comma-separated list of environment variables to capture [default: SHELL]
#[arg(long, value_name = "VARS")]
/// Specify which environment variables to capture and include in the recording metadata. This helps ensure the recording context is preserved, e.g., for auditing. Provide a comma-separated list of variable names, for example: --rec-env "USER,SHELL,TERM". If not specified, only the SHELL variable is captured by default. Can also be set via the config file option recording.rec_env.
#[arg(
long,
value_name = "VARS",
help = "Comma-separated list of environment variables to capture [default: SHELL]",
long_help
)]
pub rec_env: Option<String>,
/// Append to an existing recording file
#[arg(short, long)]
/// Append the new session to an existing recording file instead of creating a new one. This allows you to continue a previous recording session. The timing will be adjusted to maintain continuity from where the previous recording ended. Cannot be used together with --overwrite.
#[arg(short, long, help = "Append to an existing recording file", long_help)]
pub append: bool,
/// Overwrite the output file if it already exists
#[arg(long, conflicts_with = "append")]
/// Overwrite the output file if it already exists. By default, asciinema will refuse to overwrite existing files to prevent accidental data loss. Cannot be used together with --append.
#[arg(
long,
conflicts_with = "append",
help = "Overwrite the output file if it already exists",
long_help
)]
pub overwrite: bool,
/// Title of the recording
#[arg(short, long)]
/// Set a descriptive title for the recording that will be stored in the recording metadata. This title may be displayed by players and is useful for organizing and identifying recordings. For example: --title "Installing Podman on Ubuntu".
#[arg(short, long, help = "Title of the recording", long_help)]
pub title: Option<String>,
/// Limit idle time to a given number of seconds
#[arg(short, long, value_name = "SECS")]
/// Limit the maximum idle time recorded between terminal events to the specified number of seconds. Long pauses (such as when you step away from the terminal) will be capped at this duration in the recording, making playback more watchable. For example, --idle-time-limit 2.0 will ensure no pause longer than 2 seconds appears in the recording. Note that this option doesn't alter the original (captured) timing information and instead embeds the idle time limit value in the metadata, which is interpreted by session players at playback time. This allows tweaking of the limit after recording. Can also be set via the config file option recording.idle_time_limit.
#[arg(
short,
long,
value_name = "SECS",
help = "Limit idle time to a given number of seconds",
long_help
)]
pub idle_time_limit: Option<f64>,
/// Headless mode - don't use the terminal for I/O
#[arg(long)]
/// Record in headless mode without using the terminal for input/output. This is useful for automated or scripted recordings where you don't want asciinema to interfere with the current terminal session. The recorded command will still execute normally, but asciinema won't display its output in your terminal. Headless mode is enabled automatically when running in an environment where a terminal is not available.
#[arg(
long,
help = "Headless mode - don't use the terminal for I/O",
long_help
)]
pub headless: bool,
/// Override session's terminal window size
#[arg(long, value_name = "COLSxROWS", value_parser = parse_window_size)]
/// Override the terminal window size used for the recording session. Specify dimensions as COLSxROWS (e.g., 80x24 for 80 columns by 24 rows). You can specify just columns (80x) or just rows (x24) to override only one dimension. This is useful for ensuring consistent recording dimensions regardless of your current terminal size.
#[arg(long, value_name = "COLSxROWS", value_parser = parse_window_size, help = "Override session's terminal window size", long_help)]
pub window_size: Option<(Option<u16>, Option<u16>)>,
/// Return the session's exit status
#[arg(long)]
/// Make the asciinema command exit with the same status code as the recorded session. By default, asciinema exits with status 0 regardless of what happens in the recorded session. With this option, if the recorded command exits with a non-zero status, asciinema will also exit with the same status.
#[arg(long, help = "Return the session's exit status", long_help)]
pub return_: bool,
#[arg(long, hide = true)]
@@ -108,190 +196,285 @@ pub struct Record {
#[derive(Debug, Args)]
pub struct Play {
/// A path or HTTP(S) URL of a recording file
/// The path to an asciicast file or HTTP(S) URL to play back. HTTP(S) URLs allow playing recordings directly from the web without need for manual downloading. Supported formats include asciicast v1, v2, and v3.
pub file: String,
/// Set playback speed
#[arg(short, long)]
/// Control the playback speed as a multiplier of the original timing. Values greater than 1.0 make playback faster, while values less than 1.0 make it slower. For example, --speed 2.0 plays at double speed, while --speed 0.5 plays at half speed. The default is 1.0 (original speed). Can also be set via the config file option playback.speed.
#[arg(short, long, help = "Set playback speed", long_help)]
pub speed: Option<f64>,
/// Loop loop loop loop
#[arg(short, long, name = "loop")]
/// Enable continuous looping of the recording. When the recording reaches the end, it will automatically restart from the beginning. This continues indefinitely until you interrupt playback with <ctrl+c>.
#[arg(
short,
long,
name = "loop",
help = "Loop playback continuously",
long_help
)]
pub loop_: bool,
/// Limit idle time to a given number of seconds
#[arg(short, long, value_name = "SECS")]
/// Limit the maximum idle time between events during playback to the specified number of seconds. Long pauses in the original recording (such as when the user stepped away) will be shortened to this duration, making playback more watchable. This overrides any idle time limit set in the recording itself or in your config file (playback.idle_time_limit).
#[arg(
short,
long,
value_name = "SECS",
help = "Limit idle time to a given number of seconds",
long_help
)]
pub idle_time_limit: Option<f64>,
/// Automatically pause on markers
#[arg(short = 'm', long)]
/// Automatically pause playback when encountering marker events. Markers are special events that can be added during recording to mark important points in a session. When this option is enabled, playback will pause at each marker, allowing you to control the flow of the demonstration. Use <space> to resume, '.' to step through events, or ']' to skip to the next marker.
#[arg(short = 'm', long, help = "Automatically pause on markers", long_help)]
pub pause_on_markers: bool,
/// Auto-resize the terminal window to match the original size (supported on some terminals)
#[arg(short = 'r', long)]
/// Automatically resize the terminal window to match the original recording dimensions. This option attempts to change your terminal size to match the size used when the recording was made, ensuring the output appears exactly as it was originally recorded. Note that this feature is only supported by some terminals and may not work in all environments.
#[arg(
short = 'r',
long,
help = "Auto-resize terminal to match original size",
long_help
)]
pub resize: bool,
}
#[derive(Debug, Args)]
#[clap(group(ArgGroup::new("mode").args(&["local", "remote"]).multiple(true).required(true)))]
pub struct Stream {
/// Stream the session via a local HTTP server
#[arg(short, long, value_name = "IP:PORT", default_missing_value = DEFAULT_LISTEN_ADDR, num_args = 0..=1)]
/// Start a local HTTP server to stream the session in real-time. Creates a web interface accessible via browser where viewers can watch the terminal session live. Optionally specify the bind address as IP:PORT (e.g., 0.0.0.0:8080 to allow external connections). If no address is provided, defaults to 127.0.0.1:8080.
#[arg(short, long, value_name = "IP:PORT", default_missing_value = DEFAULT_LISTEN_ADDR, num_args = 0..=1, help = "Stream via local HTTP server", long_help)]
pub local: Option<SocketAddr>,
/// Stream the session via a remote asciinema server
#[arg(short, long, value_name = "STREAM-ID|WS-URL", default_missing_value = "", num_args = 0..=1, value_parser = validate_forward_target)]
/// Stream the session to a remote asciinema server for public viewing. This allows sharing your session on the web with anyone who has the stream URL. You can provide either a stream ID of an existing stream configuration in your asciinema server account, or a direct WebSocket URL (ws:// or wss://) for custom servers. Omitting the value for this option lets the asciinema server either allocate a new stream ID automatically or reuse an existing one (may depend on server configuration).
#[arg(short, long, value_name = "STREAM-ID|WS-URL", default_missing_value = "", num_args = 0..=1, value_parser = validate_forward_target, help = "Stream via remote asciinema server", long_help)]
pub remote: Option<RelayTarget>,
/// Command to start in the session [default: $SHELL]
#[arg(short, long)]
/// Specify the command to execute in the streaming session. If not provided, asciinema will use your default shell from the $SHELL environment variable. This can be any command with arguments, for example: --command "python script.py" or --command "bash -l". Can also be set via config file option recording.command.
#[arg(
short,
long,
help = "Command to start in the session [default: $SHELL]",
long_help
)]
pub command: Option<String>,
/// Enable input (keyboard) recording
#[arg(long, short = 'I')]
/// Enable recording of keyboard input in addition to terminal output. When enabled, both what you type and what appears on the screen will be captured. Note that sensitive input like passwords will also be recorded when this option is enabled. If the server has stream recording enabled then keyboard input will be included in the recording file created on the server side. Can also be set via the config file option recording.rec_input.
#[arg(
long,
short = 'I',
help = "Enable input (keyboard) recording",
long_help
)]
pub rec_input: bool,
/// Comma-separated list of environment variables to capture [default: SHELL]
#[arg(long, value_name = "VARS")]
/// Specify which environment variables to capture and include in the stream metadata. Provide a comma-separated list of variable names, for example: --rec-env "USER,SHELL,TERM". If not specified, only the SHELL variable is captured by default. If the server has stream recording enabled then these environment variables will be included in the recording file created on the server side. Can also be set via the config file option recording.rec_env.
#[arg(
long,
value_name = "VARS",
help = "Comma-separated list of environment variables to capture [default: SHELL]",
long_help
)]
pub rec_env: Option<String>,
/// Title of the session
#[arg(short, long)]
/// Set a descriptive title for the streaming session. This title is displayed to viewers (when doing remote streaming with --remote). For example: --title "Building a REST API". If the server has stream recording enabled then the title will be included in the recording file created on the server side.
#[arg(short, long, help = "Title of the session", long_help)]
pub title: Option<String>,
/// Headless mode - don't use the terminal for I/O
#[arg(long)]
/// Stream in headless mode without using the terminal for input/output. This is useful for automated or scripted streaming where you don't want asciinema to interfere with the current terminal session. The streamed command will still execute normally and be visible to viewers, but won't be displayed in your local terminal. Headless mode is enabled automatically when running in an environment where a terminal is not available.
#[arg(
long,
help = "Headless mode - don't use the terminal for I/O",
long_help
)]
pub headless: bool,
/// Override session's terminal window size
#[arg(long, value_name = "COLSxROWS", value_parser = parse_window_size)]
/// Override the terminal window size used for the streaming session. Specify dimensions as COLSxROWS (e.g., 80x24 for 80 columns by 24 rows). You can specify just columns (80x) or just rows (x24) to override only one dimension. This is useful for ensuring consistent streaming dimensions regardless of your current terminal size.
#[arg(long, value_name = "COLSxROWS", value_parser = parse_window_size, help = "Override session's terminal window size", long_help)]
pub window_size: Option<(Option<u16>, Option<u16>)>,
/// Return the session's exit status
#[arg(long)]
/// Make the asciinema command exit with the same status code as the streamed session. By default, asciinema exits with status 0 regardless of what happens in the streamed session. With this option, if the streamed command exits with a non-zero status, asciinema will also exit with that same status.
#[arg(long, help = "Return the session's exit status", long_help)]
pub return_: bool,
/// Log file path
#[arg(long, value_name = "PATH")]
/// Enable logging of internal events to a file at the specified path. Useful for debugging streaming issues (connection errors, disconnections, etc.).
#[arg(long, value_name = "PATH", help = "Log file path", long_help)]
pub log_file: Option<PathBuf>,
/// asciinema server URL
#[arg(long, value_name = "URL")]
/// Specify a custom asciinema server URL for streaming to self-hosted servers. The URL should be the base URL of the server (e.g., https://asciinema.example.com). Can also be set via the environment variable ASCIINEMA_SERVER_URL or the config file option server.url. If no server URL is configured via this option, environment variable, or config file, you will be prompted to choose one (defaulting to asciinema.org), which will be saved as a default.
#[arg(long, value_name = "URL", help = "asciinema server URL", long_help)]
pub server_url: Option<String>,
}
#[derive(Debug, Args)]
pub struct Session {
/// Save the session to a file
#[arg(short, long, value_name = "PATH")]
/// Save the session to a file at the specified path. Can be combined with local and remote streaming.
#[arg(
short,
long,
value_name = "PATH",
help = "Save the session to a file",
long_help
)]
pub output_file: Option<String>,
/// Output file format [default: asciicast-v3]
#[arg(short = 'f', long, value_enum, value_name = "FORMAT")]
/// Specify the format for the output file when saving is enabled with --output-file. The default is asciicast-v3. If the output file path ends with .txt, the txt format will be selected automatically unless this option is explicitly specified.
#[arg(
short = 'f',
long,
value_enum,
value_name = "FORMAT",
help = "Output file format [default: asciicast-v3]",
long_help
)]
pub output_format: Option<Format>,
/// Stream the session via a local HTTP server
#[arg(short = 'l', long, value_name = "IP:PORT", default_missing_value = DEFAULT_LISTEN_ADDR, num_args = 0..=1)]
/// Start a local HTTP server to stream the session in real-time. Creates a web interface accessible via browser where viewers can watch the terminal session live. Optionally specify the bind address as IP:PORT (e.g., 0.0.0.0:8080 to allow external connections). If no address is provided, defaults to 127.0.0.1:8080. Can be combined with remote streaming and file output.
#[arg(short = 'l', long, value_name = "IP:PORT", default_missing_value = DEFAULT_LISTEN_ADDR, num_args = 0..=1, help = "Stream via local HTTP server", long_help)]
pub stream_local: Option<SocketAddr>,
/// Stream the session via a remote asciinema server
#[arg(short = 'r', long, value_name = "STREAM-ID|WS-URL", default_missing_value = "", num_args = 0..=1, value_parser = validate_forward_target)]
/// Stream the session to a remote asciinema server for public viewing. This allows sharing your session on the web with anyone who has the stream URL. You can provide either a stream ID of an existing stream configuration in your asciinema server account, or a direct WebSocket URL (ws:// or wss://) for custom servers. Omitting the value for this option lets the asciinema server either allocate a new stream ID automatically or reuse an existing one (may depend on server configuration). Can be combined with local streaming and file output.
#[arg(short = 'r', long, value_name = "STREAM-ID|WS-URL", default_missing_value = "", num_args = 0..=1, value_parser = validate_forward_target, help = "Stream via remote asciinema server", long_help)]
pub stream_remote: Option<RelayTarget>,
/// Command to start in the session [default: $SHELL]
#[arg(short, long)]
/// Specify the command to execute in the session. If not provided, asciinema will use your default shell from the $SHELL environment variable. This can be any command with arguments, for example: --command "python script.py" or --command "bash -l". Can also be set via config file option recording.command.
#[arg(
short,
long,
help = "Command to start in the session [default: $SHELL]",
long_help
)]
pub command: Option<String>,
/// Enable input (keyboard) recording
#[arg(long, short = 'I')]
/// Enable recording of keyboard input in addition to terminal output. When enabled, both what you type and what appears on the screen will be captured. Note that sensitive input like passwords will also be recorded when this option is enabled. If the server has stream recording enabled then keyboard input will be included in the recording file created on the server side. Can also be set via the config file option recording.rec_input.
#[arg(
long,
short = 'I',
help = "Enable input (keyboard) recording",
long_help
)]
pub rec_input: bool,
/// Comma-separated list of environment variables to capture [default: SHELL]
#[arg(long, value_name = "VARS")]
/// Specify which environment variables to capture and include in the session metadata. Provide a comma-separated list of variable names, for example: --rec-env "USER,SHELL,TERM". If not specified, only the SHELL variable is captured by default. If the server has stream recording enabled then these environment variables will be included in the recording file created on the server side. Can also be set via config file option recording.rec_env.
#[arg(
long,
value_name = "VARS",
help = "Comma-separated list of environment variables to capture [default: SHELL]",
long_help
)]
pub rec_env: Option<String>,
/// Append to an existing recording file
#[arg(short, long)]
/// Append the new session to an existing recording file instead of creating a new one. This allows you to continue a previous recording session. The timing will be adjusted to maintain continuity from where the previous recording ended. Cannot be used together with --overwrite. Only applies when --output-file is specified.
#[arg(short, long, help = "Append to an existing recording file", long_help)]
pub append: bool,
/// Overwrite the output file if it already exists
#[arg(long, conflicts_with = "append")]
/// Overwrite the output file if it already exists. By default, asciinema will refuse to overwrite existing files to prevent accidental data loss. Cannot be used together with --append. Only applies when --output-file is specified.
#[arg(
long,
conflicts_with = "append",
help = "Overwrite the output file if it already exists",
long_help
)]
pub overwrite: bool,
/// Title of the session
#[arg(short, long)]
/// Set a descriptive title for the session that will be stored in the recording metadata and displayed to stream viewers (when doing remote streaming with --remote). For example: --title "Installing Podman on Ubuntu". If the server has stream recording enabled then the title will be included in the recording file created on the server side.
#[arg(short, long, help = "Title of the session", long_help)]
pub title: Option<String>,
/// Limit idle time to a given number of seconds
#[arg(short, long, value_name = "SECS")]
/// Limit the maximum idle time recorded between terminal events to the specified number of seconds. Long pauses (such as when you step away from the terminal) will be capped at this duration in the recording, making playback more watchable. For example, --idle-time-limit 2.0 will ensure no pause longer than 2 seconds appears in the recording. Only applies when --output-file is specified. Note that this option doesn't alter the original (captured) timing information and instead it embeds the idle time limit value in the metadata, which is interpreted by session players at playback time. This allows tweaking of the limit after recording. Can also be set via config file option recording.idle_time_limit.
#[arg(
short,
long,
value_name = "SECS",
help = "Limit idle time to a given number of seconds",
long_help
)]
pub idle_time_limit: Option<f64>,
/// Headless mode - don't use the terminal for I/O
#[arg(long)]
/// Run the session in headless mode without using the terminal for input/output. This is useful for automated or scripted sessions where you don't want asciinema to interfere with the current terminal session. The session command will still execute normally and be recorded/streamed, but won't be displayed in your local terminal. Headless mode is enabled automatically when running in an environment where a terminal is not available.
#[arg(
long,
help = "Headless mode - don't use the terminal for I/O",
long_help
)]
pub headless: bool,
/// Override session's terminal window size
#[arg(long, value_name = "COLSxROWS", value_parser = parse_window_size)]
/// Override the terminal window size used for the session. Specify dimensions as COLSxROWS (e.g., 80x24 for 80 columns by 24 rows). You can specify just columns (80x) or just rows (x24) to override only one dimension. This is useful for ensuring consistent recording dimensions regardless of your current terminal size.
#[arg(long, value_name = "COLSxROWS", value_parser = parse_window_size, help = "Override session's terminal window size", long_help)]
pub window_size: Option<(Option<u16>, Option<u16>)>,
/// Return the session's exit status
#[arg(long)]
/// Make the asciinema command exit with the same status code as the session command. By default, asciinema exits with status 0 regardless of what happens in the session. With this option, if the session command exits with a non-zero status, asciinema will also exit with that same status.
#[arg(long, help = "Return the session's exit status", long_help)]
pub return_: bool,
/// Log file path
#[arg(long, value_name = "PATH")]
/// Enable logging of internal events to a file at the specified path. Useful for debugging streaming issues (connection errors, disconnections, etc.).
#[arg(long, value_name = "PATH", help = "Log file path", long_help)]
pub log_file: Option<PathBuf>,
/// asciinema server URL
#[arg(long, value_name = "URL")]
/// Specify a custom asciinema server URL for streaming to self-hosted servers. The URL should be the base URL of the server (e.g. https://asciinema.example.com). Can also be set via environment variable ASCIINEMA_SERVER_URL or config file option server.url. If no server URL is configured via this option, environment variable, or config file, you will be prompted to choose one (defaulting to asciinema.org), which will be saved as a default.
#[arg(long, value_name = "URL", help = "asciinema server URL", long_help)]
pub server_url: Option<String>,
}
#[derive(Debug, Args)]
pub struct Cat {
#[arg(required = true, num_args = 2..)]
/// List of recording files to concatenate. Provide at least two file paths (local files or HTTP(S) URLs). The files will be combined in the order specified. All files must be in asciicast format.
#[arg(required = true, num_args = 2.., help = "Recording files to concatenate", long_help)]
pub file: Vec<String>,
}
#[derive(Debug, Args)]
pub struct Convert {
/// Input asciicast file path, HTTP(S) URL, or '-' (for stdin)
/// The source recording to convert. Can be a local file path, HTTP(S) URL for remote files, or '-' to read from standard input. Remote URLs allow converting recordings directly from the web without need for manual downloading. Supported input formats include asciicast v1, v2 and v3.
pub input: String,
/// Output file path, or '-' (for stdout)
/// The output path for the converted recording. Can be a file path or '-' to write to standard output.
pub output: String,
/// Output file format [default: asciicast-v3]
#[arg(short = 'f', long, value_enum, value_name = "FORMAT")]
/// Specify the format for the converted recording. The default is asciicast-v3. If the output file path ends with .txt, the txt format will be selected automatically unless this option is explicitly specified.
#[arg(
short = 'f',
long,
value_enum,
value_name = "FORMAT",
help = "Output file format [default: asciicast-v3]",
long_help
)]
pub output_format: Option<Format>,
/// Overwrite the output file if it already exists
#[arg(long)]
/// Overwrite the output file if it already exists. By default, asciinema will refuse to overwrite existing files to prevent accidental data loss. Has no effect when writing to stdout ('-').
#[arg(
long,
help = "Overwrite the output file if it already exists",
long_help
)]
pub overwrite: bool,
}
#[derive(Debug, Args)]
pub struct Upload {
/// Path to an asciicast file to upload
/// The path to the asciicast recording file to upload. Must be a file in a supported asciicast format (v1, v2, or v3). After successful upload, you'll receive a URL where the recording can be viewed and shared.
pub file: String,
/// asciinema server URL
#[arg(long, value_name = "URL")]
/// Specify a custom asciinema server URL for uploading to self-hosted servers. The URL should be the base URL of the server (e.g. https://asciinema.example.com). Can also be set via environment variable ASCIINEMA_SERVER_URL or config file option server.url. If no server URL is configured via this option, environment variable, or config file, you will be prompted to choose one (defaulting to asciinema.org), which will be saved as a default.
#[arg(long, value_name = "URL", help = "asciinema server URL", long_help)]
pub server_url: Option<String>,
}
#[derive(Debug, Args)]
pub struct Auth {
/// asciinema server URL
#[arg(long, value_name = "URL")]
/// Specify a custom asciinema server URL for authenticating with self-hosted servers. The URL should be the base URL of the server (e.g. https://asciinema.example.com). Can also be set via environment variable ASCIINEMA_SERVER_URL or config file option server.url. If no server URL is configured via this option, environment variable, or config file, you will be prompted to choose one (defaulting to asciinema.org), which will be saved as a default.
#[arg(long, value_name = "URL", help = "asciinema server URL", long_help)]
pub server_url: Option<String>,
}
#[derive(Clone, Copy, Debug, PartialEq, ValueEnum)]
pub enum Format {
/// Full-featured session format, with timing and metadata (current generation) - https://docs.asciinema.org/manual/asciicast/v3/
AsciicastV3,
/// Full-featured session format, with timing and metadata (previous generation) - https://docs.asciinema.org/manual/asciicast/v2/
AsciicastV2,
/// Raw terminal output, including control sequences, without timing and metadata
Raw,
/// Plain text without colors or control sequences, human-readable
Txt,
}