From 0e3b4556554d47abc6e6f85231f8e87f5d4b9bcc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:05:43 +0000 Subject: [PATCH] Restructure commands: list channels/guilds subcommands with positional parameters Agent-Logs-Url: https://github.com/Tyrrrz/DiscordChatExporter/sessions/27f23ff6-5b39-46d3-a7dc-387749ee63fa Co-authored-by: Tyrrrz <1935960+Tyrrrz@users.noreply.github.com> --- .docs/Using-the-CLI.md | 94 +++++------ .../Commands/ExportChannelsCommand.cs | 11 +- .../Commands/GetChannelsCommand.cs | 151 ++++++++++-------- .../Commands/GetDirectChannelsCommand.cs | 2 +- .../Commands/GetGuildsCommand.cs | 2 +- 5 files changed, 140 insertions(+), 120 deletions(-) diff --git a/.docs/Using-the-CLI.md b/.docs/Using-the-CLI.md index 7da211b8..a3d626d7 100644 --- a/.docs/Using-the-CLI.md +++ b/.docs/Using-the-CLI.md @@ -33,13 +33,13 @@ Type the following command in your terminal of choice, then press ENTER to run i ## CLI commands -| Command | Description | -| -------- | ---------------------------------------------------- | -| export | Exports one or more channels | -| channels | Outputs the list of channels in the given server | -| dm | Outputs the list of direct message channels | -| guilds | Outputs the list of accessible servers | -| guide | Explains how to obtain token, server, and channel ID | +| Command | Description | +| ----------------- | ---------------------------------------------------- | +| export | Exports one or more channels | +| list channels | Outputs the list of channels in the given server(s) | +| list channels dm | Outputs the list of direct message channels | +| list guilds | Outputs the list of accessible servers | +| guide | Explains how to obtain token, server, and channel ID | To use the commands, you'll need a token. For the instructions on how to get a token, please refer to [this page](Token-and-IDs.md), or run `./DiscordChatExporter.Cli guide`. @@ -57,10 +57,10 @@ For example, to figure out how to use the `export` command, run: ## Export a specific channel -You can quickly export with DCE's default settings by using just `-t token` and `-c channelid`. +You can quickly export with DCE's default settings by using just `-t token` and the channel ID as a positional argument. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 ``` #### Changing the format @@ -69,7 +69,7 @@ You can change the export format to `HtmlDark`, `HtmlLight`, `PlainText` `Json` format is `HtmlDark`. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -f Json +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -f Json ``` #### Changing the output filename @@ -77,7 +77,7 @@ format is `HtmlDark`. You can change the filename by using `-o name.ext`. e.g. for the `HTML` format: ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -o myserver.html +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -o myserver.html ``` #### Changing the output directory @@ -87,7 +87,7 @@ extension. If any of the folders in the path have a space in its name, escape them with quotes ("). ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -o "C:\Discord Exports" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -o "C:\Discord Exports" ``` #### Changing the filename and output directory @@ -97,7 +97,7 @@ Note that the filename must have an extension, otherwise it will be considered a If any of the folders in the path have a space in its name, escape them with quotes ("). ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -o "C:\Discord Exports\myserver.html" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -o "C:\Discord Exports\myserver.html" ``` #### Generating the filename and output directory dynamically @@ -105,7 +105,7 @@ If any of the folders in the path have a space in its name, escape them with quo You can use template tokens to generate the output file path based on the server and channel metadata. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -o "C:\Discord Exports\%G\%T\%C.html" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -o "C:\Discord Exports\%G\%T\%C.html" ``` Assuming you are exporting a channel named `"my-channel"` in the `"Text channels"` category from a server @@ -133,13 +133,13 @@ You can use partitioning to split files after a given number of messages or file For example, a channel with 36 messages set to be partitioned every 10 messages will output 4 files. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -p 10 +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -p 10 ``` A 45 MB channel set to be partitioned every 20 MB will output 3 files. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 -p 20mb +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 -p 20mb ``` #### Downloading assets @@ -150,7 +150,7 @@ downloaded when using the plain text (TXT) export format. A folder containing the assets will be created along with the exported chat. They must be kept together. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --media +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --media ``` #### Reusing assets @@ -159,7 +159,7 @@ Previously downloaded assets can be reused to skip redundant downloads as long a same folder. Using this option can speed up future exports. This option requires the `--media` option. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --media --reuse-media +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --media --reuse-media ``` #### Changing the media directory @@ -168,7 +168,7 @@ By default, the media directory is created alongside the exported chat. You can providing a path that ends with a slash. All of the exported media will be stored in this directory. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --media --media-dir "C:\Discord Media" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --media --media-dir "C:\Discord Media" ``` #### Changing the date format @@ -177,7 +177,7 @@ You can customize how dates are formatted in the exported files by using `--loca locales. The default locale is `en-US`. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --locale "de-DE" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --locale "de-DE" ``` #### Date ranges @@ -186,14 +186,14 @@ locales. The default locale is `en-US`. Use `--before` to export messages sent before the provided date. E.g. messages sent before September 18th, 2019: ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --before 2019-09-18 +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --before 2019-09-18 ``` **Messages sent after a date** Use `--after` to export messages sent after the provided date. E.g. messages sent after September 17th, 2019 11:34 PM: ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --after "2019-09-17 23:34" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --after "2019-09-17 23:34" ``` **Messages sent in a date range** @@ -201,7 +201,7 @@ Use `--before` and `--after` to export messages sent during the provided date ra September 17th, 2019 11:34 PM and September 18th: ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --after "2019-09-17 23:34" --before "2019-09-18" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --after "2019-09-17 23:34" --before "2019-09-18" ``` You can try different formats like `17-SEP-2019 11:34 PM` or even refine your ranges down to @@ -215,79 +215,83 @@ formats [here](https://docs.microsoft.com/en-us/dotnet/standard/base-types/custo Use `--filter` to filter what messages are included in the export. ```console -./DiscordChatExporter.Cli export -t "mfa.Ifrn" -c 53555 --filter "from:Tyrrrz has:image" +./DiscordChatExporter.Cli export -t "mfa.Ifrn" 53555 --filter "from:Tyrrrz has:image" ``` Documentation on message filter syntax can be found [here](https://github.com/Tyrrrz/DiscordChatExporter/blob/prime/.docs/Message-filters.md). ### Export channels from a specific server -To export all channels in a specific server, use the `channels` command to list channels and pipe the result to `export`: +To export all channels in a specific server, use `list channels` to list channels and pipe the result to `export`: ```console -./DiscordChatExporter.Cli channels -t "mfa.Ifrn" -g 21814 | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels -t "mfa.Ifrn" 21814 | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" ``` > **Tip**: To avoid repeating `--token` (or `-t`) twice, set the `DISCORD_TOKEN` environment variable: `export DISCORD_TOKEN="mfa.Ifrn"` (Linux/macOS) or `set DISCORD_TOKEN=mfa.Ifrn` (Windows). Then you can omit `-t` from both commands. -#### Including threads - -By default, threads are not included. You can change this behavior by passing `--include-threads` to the `channels` command. It has possible values of `none`, `active`, or `all`, indicating which threads should be included. To include both active and archived threads, use `--include-threads all`. +You can also list channels for multiple guilds at once: ```console -./DiscordChatExporter.Cli channels -t "mfa.Ifrn" -g 21814 --include-threads all | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels -t "mfa.Ifrn" 21814 35930 | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +``` + +#### Including threads + +By default, threads are not included. You can change this behavior by passing `--include-threads` to the `list channels` command. It has possible values of `none`, `active`, or `all`, indicating which threads should be included. To include both active and archived threads, use `--include-threads all`. + +```console +./DiscordChatExporter.Cli list channels -t "mfa.Ifrn" 21814 --include-threads all | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" ``` #### Including voice channels -By default, voice channels are included. You can change this behavior by passing `--include-vc false` to the `channels` command. +By default, voice channels are included. You can change this behavior by passing `--include-vc false` to the `list channels` command. ```console -./DiscordChatExporter.Cli channels -t "mfa.Ifrn" -g 21814 --include-vc false | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels -t "mfa.Ifrn" 21814 --include-vc false | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" ``` ### Export all channels -To export all accessible channels, first list all guilds and then pipe each guild's channels to `export`. You can also use `dm` to include direct message channels. - To export all DMs: ```console -./DiscordChatExporter.Cli dm -t "mfa.Ifrn" | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels dm -t "mfa.Ifrn" | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" ``` ### List channels in a server -To list the channels available in a specific server, use the `channels` command and provide the server ID through the `-g|--guild` option: +To list the channels available in a specific server, use the `list channels` command and provide the server ID as an argument: ```console -./DiscordChatExporter.Cli channels -t "mfa.Ifrn" -g 21814 +./DiscordChatExporter.Cli list channels -t "mfa.Ifrn" 21814 ``` -When the output is redirected or piped, the `channels` command prints only channel IDs (one per line). This allows you to pipe the output directly to the `export` command: +When the output is redirected or piped, the `list channels` command prints only channel IDs (one per line). This allows you to pipe the output directly to the `export` command: ```console -./DiscordChatExporter.Cli channels -t "mfa.Ifrn" -g 21814 | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels -t "mfa.Ifrn" 21814 | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" ``` ### List direct message channels -To list all DM channels accessible to the current account, use the `dm` command: +To list all DM channels accessible to the current account, use the `list channels dm` command: ```console -./DiscordChatExporter.Cli dm -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels dm -t "mfa.Ifrn" ``` -When the output is redirected or piped, the `dm` command prints only channel IDs (one per line). This allows you to pipe the output directly to the `export` command: +When the output is redirected or piped, the `list channels dm` command prints only channel IDs (one per line). This allows you to pipe the output directly to the `export` command: ```console -./DiscordChatExporter.Cli dm -t "mfa.Ifrn" | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" +./DiscordChatExporter.Cli list channels dm -t "mfa.Ifrn" | ./DiscordChatExporter.Cli export -t "mfa.Ifrn" ``` ### List servers -To list all servers accessible by the current account, use the `guilds` command: +To list all servers accessible by the current account, use the `list guilds` command: ```console -./DiscordChatExporter.Cli guilds -t "mfa.Ifrn" > C:\path\to\output.txt +./DiscordChatExporter.Cli list guilds -t "mfa.Ifrn" > C:\path\to\output.txt ``` diff --git a/DiscordChatExporter.Cli/Commands/ExportChannelsCommand.cs b/DiscordChatExporter.Cli/Commands/ExportChannelsCommand.cs index 1fbb085e..fc5f4628 100644 --- a/DiscordChatExporter.Cli/Commands/ExportChannelsCommand.cs +++ b/DiscordChatExporter.Cli/Commands/ExportChannelsCommand.cs @@ -13,14 +13,13 @@ namespace DiscordChatExporter.Cli.Commands; [Command("export", Description = "Exports one or multiple channels.")] public partial class ExportChannelsCommand : ExportCommandBase { - // TODO: change this to plural (breaking change) - [CommandOption( - "channel", - 'c', + [CommandParameter( + 0, + Name = "channel-ids", Description = "Channel ID(s). " + "If provided with category ID(s), all channels inside those categories will be exported. " + "If not provided, channel IDs are read from standard input (one per line), " - + "enabling piping from the 'channels' or 'dm' commands." + + "enabling piping from the 'list channels' or 'list channels dm' commands." )] public IReadOnlyList ChannelIds { get; set; } = []; @@ -60,7 +59,7 @@ public partial class ExportChannelsCommand : ExportCommandBase { throw new CommandException( "No channel IDs provided. " - + "Specify channel IDs via the '--channel' option or pipe them from the 'channels' or 'dm' commands." + + "Specify channel IDs as arguments or pipe them from the 'list channels' or 'list channels dm' commands." ); } diff --git a/DiscordChatExporter.Cli/Commands/GetChannelsCommand.cs b/DiscordChatExporter.Cli/Commands/GetChannelsCommand.cs index 59b43df9..97559cdd 100644 --- a/DiscordChatExporter.Cli/Commands/GetChannelsCommand.cs +++ b/DiscordChatExporter.Cli/Commands/GetChannelsCommand.cs @@ -1,4 +1,5 @@ using System; +using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using CliFx.Binding; @@ -7,15 +8,16 @@ using DiscordChatExporter.Cli.Commands.Base; using DiscordChatExporter.Cli.Commands.Converters; using DiscordChatExporter.Cli.Commands.Shared; using DiscordChatExporter.Core.Discord; +using DiscordChatExporter.Core.Discord.Data; using DiscordChatExporter.Core.Utils.Extensions; namespace DiscordChatExporter.Cli.Commands; -[Command("channels", Description = "Get the list of channels in a server.")] +[Command("list channels", Description = "Gets the list of channels in one or more servers.")] public partial class GetChannelsCommand : DiscordCommandBase { - [CommandOption("guild", 'g', Description = "Server ID.")] - public required Snowflake GuildId { get; set; } + [CommandParameter(0, Name = "guild-ids", Description = "Server ID(s).")] + public required IReadOnlyList GuildIds { get; set; } [CommandOption("include-vc", Description = "Include voice channels.")] public bool IncludeVoiceChannels { get; set; } = true; @@ -33,94 +35,109 @@ public partial class GetChannelsCommand : DiscordCommandBase var cancellationToken = console.RegisterCancellationHandler(); - var channels = (await Discord.GetGuildChannelsAsync(GuildId, cancellationToken)) - .Where(c => !c.IsCategory) - .Where(c => IncludeVoiceChannels || !c.IsVoice) - .OrderBy(c => c.Parent?.Position) - .ThenBy(c => c.Name) - .ToArray(); + foreach (var guildId in GuildIds) + { + var channels = (await Discord.GetGuildChannelsAsync(guildId, cancellationToken)) + .Where(c => !c.IsCategory) + .Where(c => IncludeVoiceChannels || !c.IsVoice) + .OrderBy(c => c.Parent?.Position) + .ThenBy(c => c.Name) + .ToArray(); - var channelIdMaxLength = channels - .Select(c => c.Id.ToString().Length) - .OrderDescending() - .FirstOrDefault(); - - var threads = - ThreadInclusionMode != ThreadInclusionMode.None - ? ( - await Discord.GetGuildThreadsAsync( - GuildId, - ThreadInclusionMode == ThreadInclusionMode.All, - null, - null, - cancellationToken + var threads = + ThreadInclusionMode != ThreadInclusionMode.None + ? ( + await Discord.GetGuildThreadsAsync( + guildId, + ThreadInclusionMode == ThreadInclusionMode.All, + null, + null, + cancellationToken + ) ) - ) - .OrderBy(c => c.Name) - .ToArray() - : []; + .OrderBy(c => c.Name) + .ToArray() + : []; - // If output is redirected, print only channel IDs (one per line) for easy piping - if (console.IsOutputRedirected) - { - foreach (var channel in channels) + // If output is redirected, print only channel IDs (one per line) for easy piping + if (console.IsOutputRedirected) { - await console.Output.WriteLineAsync(channel.Id.ToString()); - foreach (var channelThread in threads.Where(t => t.Parent?.Id == channel.Id)) - await console.Output.WriteLineAsync(channelThread.Id.ToString()); + foreach (var channel in channels) + { + await console.Output.WriteLineAsync(channel.Id.ToString()); + foreach (var channelThread in threads.Where(t => t.Parent?.Id == channel.Id)) + await console.Output.WriteLineAsync(channelThread.Id.ToString()); + } } - } - else - { - foreach (var channel in channels) + else { - // Channel ID - await console.Output.WriteAsync( - channel.Id.ToString().PadRight(channelIdMaxLength, ' ') - ); + // Show guild header when listing multiple guilds + if (GuildIds.Count > 1) + { + var guild = await Discord.GetGuildAsync(guildId, cancellationToken); - // Separator - using (console.WithForegroundColor(ConsoleColor.DarkGray)) - await console.Output.WriteAsync(" | "); + using (console.WithForegroundColor(ConsoleColor.Cyan)) + await console.Output.WriteLineAsync($"{guild.Id} | {guild.Name}"); + } - // Channel name - using (console.WithForegroundColor(ConsoleColor.White)) - await console.Output.WriteLineAsync(channel.GetHierarchicalName()); - - var channelThreads = threads.Where(t => t.Parent?.Id == channel.Id).ToArray(); - var channelThreadIdMaxLength = channelThreads - .Select(t => t.Id.ToString().Length) + var channelIdMaxLength = channels + .Select(c => c.Id.ToString().Length) .OrderDescending() .FirstOrDefault(); - foreach (var channelThread in channelThreads) + foreach (var channel in channels) { - // Indent - await console.Output.WriteAsync(" * "); - - // Thread ID + // Channel ID await console.Output.WriteAsync( - channelThread.Id.ToString().PadRight(channelThreadIdMaxLength, ' ') + channel.Id.ToString().PadRight(channelIdMaxLength, ' ') ); // Separator using (console.WithForegroundColor(ConsoleColor.DarkGray)) await console.Output.WriteAsync(" | "); - // Thread name + // Channel name using (console.WithForegroundColor(ConsoleColor.White)) - await console.Output.WriteAsync($"Thread / {channelThread.Name}"); + await console.Output.WriteLineAsync(channel.GetHierarchicalName()); - // Separator - using (console.WithForegroundColor(ConsoleColor.DarkGray)) - await console.Output.WriteAsync(" | "); + var channelThreads = threads.Where(t => t.Parent?.Id == channel.Id).ToArray(); + var channelThreadIdMaxLength = channelThreads + .Select(t => t.Id.ToString().Length) + .OrderDescending() + .FirstOrDefault(); - // Thread status - using (console.WithForegroundColor(ConsoleColor.White)) - await console.Output.WriteLineAsync( - channelThread.IsArchived ? "Archived" : "Active" + foreach (var channelThread in channelThreads) + { + // Indent + await console.Output.WriteAsync(" * "); + + // Thread ID + await console.Output.WriteAsync( + channelThread.Id.ToString().PadRight(channelThreadIdMaxLength, ' ') ); + + // Separator + using (console.WithForegroundColor(ConsoleColor.DarkGray)) + await console.Output.WriteAsync(" | "); + + // Thread name + using (console.WithForegroundColor(ConsoleColor.White)) + await console.Output.WriteAsync($"Thread / {channelThread.Name}"); + + // Separator + using (console.WithForegroundColor(ConsoleColor.DarkGray)) + await console.Output.WriteAsync(" | "); + + // Thread status + using (console.WithForegroundColor(ConsoleColor.White)) + await console.Output.WriteLineAsync( + channelThread.IsArchived ? "Archived" : "Active" + ); + } } + + if (GuildIds.Count > 1) + await console.Output.WriteLineAsync(); } } } diff --git a/DiscordChatExporter.Cli/Commands/GetDirectChannelsCommand.cs b/DiscordChatExporter.Cli/Commands/GetDirectChannelsCommand.cs index b395b3cc..e2251570 100644 --- a/DiscordChatExporter.Cli/Commands/GetDirectChannelsCommand.cs +++ b/DiscordChatExporter.Cli/Commands/GetDirectChannelsCommand.cs @@ -9,7 +9,7 @@ using DiscordChatExporter.Core.Utils.Extensions; namespace DiscordChatExporter.Cli.Commands; -[Command("dm", Description = "Gets the list of all direct message channels.")] +[Command("list channels dm", Description = "Gets the list of direct message channels.")] public partial class GetDirectChannelsCommand : DiscordCommandBase { public override async ValueTask ExecuteAsync(IConsole console) diff --git a/DiscordChatExporter.Cli/Commands/GetGuildsCommand.cs b/DiscordChatExporter.Cli/Commands/GetGuildsCommand.cs index 6d8b5410..c089fe29 100644 --- a/DiscordChatExporter.Cli/Commands/GetGuildsCommand.cs +++ b/DiscordChatExporter.Cli/Commands/GetGuildsCommand.cs @@ -9,7 +9,7 @@ using DiscordChatExporter.Core.Utils.Extensions; namespace DiscordChatExporter.Cli.Commands; -[Command("guilds", Description = "Gets the list of accessible servers.")] +[Command("list guilds", Description = "Gets the list of accessible servers.")] public partial class GetGuildsCommand : DiscordCommandBase { public override async ValueTask ExecuteAsync(IConsole console)