ChatKeeper Quick Start Guide

ChatKeeper is a command line program that you run by typing commands into your terminal or command prompt.

This quick start guide includes the following sections:

Preparation

First, please read the Terms of Service and EULA. It's a quick read and (we believe) a reasonable policy, but it's important that we start on the same page.

Installation

Installation is not required; you can simply download the program file and run it. You will probably find it easier to run if you place this file somewhere in your path.

Installing your ChatKeeper License (optional)

If you chose to purchase a license, thanks! You can enable ChatKeeper's full functionality with a one-time command that saves this license to your hard drive.

Your license is a long line of letters and numbers. You definitely won't want to type it in by hand, so start by finding the email containing your license and selecting the license text by double-clicking or triple-clicking on it, then copy it to your clipboard.

Then, to install the license, run:

chatkeeper install-license [paste the long license code]

It will end up looking something like:

chatkeeper install-license xYOURzEMAILzCOMxIc5OXgAAABsAAA...

You'll see a confirmation message that the license installation succeeded, and then you'll be ready to continue with all of ChatKeeper's functionality.

If you see an error, double-check that you copied the license correctly and try again.

Exporting your ChatGPT Conversations

Before you run ChatKeeper, and whenever you want to update your local copies of your conversations, you will need an export of your ChatGPT conversations for it to operate on.

Exporting from the Web UI

  1. Open the user menu in the upper-right corner and choose "Settings"
Image showing where to find the "Settings" menu option
Where to find the "Settings" menu
  1. Choose "Data controls" on the left side and then click "Export"
Image showing where to find the "Export" button
Where to find the "Export" button

Exporting from the App

  1. Tap your name in the lower-left corner and then tap "Data Controls"
Image showing the "Settings" menu
The "Settings" menu
  1. Tap "Export Data"
Image showing where to find the "Export Data" button
Where to find the "Export Data" button

Receiving your Export Data

After exporting your data from either the web UI or the app, you will receive an email from OpenAI containing your exported data. This usually arrives quickly, but if you don't receive it after some time, check out the OpenAI Community Site to see if exports have stopped working. This has happened a few times before and OpenAI usually gets it working again within a few days.

Once you receive the email, download the .zip file using the link provided.

The rest of this document will refer to the downloaded zip file as chatgpt_export.zip, although in reality the filename will probably start with a long run of letters and numbers and end with a date and time before the .zip extension, like d6678f54...8f07fa6f-2024-09-03-12-19-36.zip (although yours will be different from the example here).

You may want to rename this file for your own convenience after downloading it.

Examples

ChatKeeper provides several options to guide its behavior. This section will start with simple usage and build up to more complicated scenarios.

Note: You can combine multiple command-line options to tailor the functionality to your specific needs.

The base command: chatkeeper keep

The chatkeeper keep command is the base command that everything else builds on. All commands in this section will start with this.

Getting help for all options

For the full list of options, what they do, and how they work, use the --help flag:

chatkeeper keep --help

Being extra safe, or "don't actually touch my files!"

You can run chatkeeper keep in a safe mode that does not actually write any data to your hard drive - instead, it only tells you what it would do.

Add the -d or --dryrun option to any chatkeeper keep command in order to execute the command as a "dry run" so you can see what it is going to do:

chatkeeper keep --dryrun [rest of command...]

Getting extra detail when running ChatKeeper

Add the -v or --verbose option to any chatkeeper keep command in order to get extra detail while it is running:

chatkeeper keep --verbose [rest of command...]

Converting your ChatGPT conversations to Markdown

To convert your conversations and store the results in C:\path\to\output_directory, run:

chatkeeper keep chatgpt_export.zip C:\path\to\output_directory

If any part of your command contains spaces, be sure to quote that part of the command, like:

chatkeeper keep chatgpt_export.zip "C:\path\to\My Output Directory"

If you run this again with the same chatgpt_export.zip, ChatKeeper will notice that there is nothing to do, even if you rename some of the files in the output directory. If you run it with a new chatgpt_export.zip, ChatKeeper will find and update any previously exported conversations that you have continued since your previous update, even if you have renamed them.

Specifying a folder/subdirectory for new conversations

If you are organizing your conversations into folders after exporting them, then you might want to put new conversations within a specific folder inside your output directory. You could think of it as an "inbox" or "other" or "uncategorized" folder. Running ChatKeeper again with a new chatgpt_export.zip file will find the conversations you have moved (within the output directory) and update those in place, while putting new conversations into the folder you specify.

This is very helpful when using "second brain" applications, like Obsidian.

To do this, use the -p or --path option:

chatkeeper keep -p "My ChatGPT Conversations" chatgpt_export.zip "C:\path\to\My Obsidian Vault"

This will store new conversations in a subdirectory called "My ChatGPT Conversations" under your C:\path\to\My Obsidian Vault directory, while updating other conversations wherever you may have moved or renamed them within C:\path\to\My Obsidian Vault.

Limiting the date range of converted conversations

Note: this option requires a license.

If you only want to convert conversations that occur before and/or after certain dates, use:

These options expect a date in YYYY-MM-DD format, and may be used together to specify a range of dates.

For example, to only convert conversations that took place in January, 2004, your command might look like:

chatkeeper keep --after 2024-01-01 --before 2024-02-01 chatgpt_export.zip "C:\path\to\My Output Directory"

Skipping the "scan my output directory" phase

As noted above, ChatKeeper will find and update any previously converted conversations that you have continued since your previous update, even if you have renamed them. In order to accomplish this, the first thing that chatkeeper keep does is scan your output directory to find them.

To skip this step for any reason, add the -n or --noscan option to your command line. Note: if you have previously moved or renamed any converted conversations within your output directory, ChatKeeper will be unaware of them and will create duplicate copies as a result.

chatkeeper keep --noscan [rest of command...]

Rewriting all conversations regardless of whether they have been updated

As noted above, ChatKeeper will find and update any previously converted conversations that you have continued since your previous update, even if you have renamed them. If the conversations have NOT been continued at ChatGPT since your previous update, ChatKeeper will not rewrite those files.

You can force ChatKeeper to rewrite these files even if the conversations have not been updated by adding the -f or --force option to your command line. This might be helpful if you have accidentally modified the files, or if a new version of ChatKeeper is released with changes in its output formatting that you would like applied to all of your conversations.

chatkeeper keep --force [rest of command...]

Skipping archived conversations

Note: this option requires a license.

ChatGPT allows you to archive individual conversations. This removes them from your conversation list in the left panel of the web page, but they will still be present in your chatgpt_export.zip files.

To skip these conversations during the conversion process, add the -s or --skip-archived option to your command line:

chatkeeper keep --skip-archived [rest of command...]

Combining options: a real example

As mentioned above, options can be combined. This example uses several at the same time in order to:

chatkeeper keep -a 2024-01-01 -b 2025-01-01 -p "My ChatGPT Conversations" --skip-archived -f -v --dry-run chatgpt_export.zip "C:\path\to\My Output Directory"

If you are satisfied with the results of the dry run, then you can remove the --dry-run option to repeat the command and actually perform the operations.

That's It!

Go give it a try - I hope you find it useful!

Martian Software, Inc. footer logo