{"id":13408020,"url":"https://github.com/npiv/chatblade","last_synced_at":"2025-05-14T17:02:29.037Z","repository":{"id":143585132,"uuid":"616187681","full_name":"npiv/chatblade","owner":"npiv","description":"A CLI Swiss Army Knife for ChatGPT","archived":false,"fork":false,"pushed_at":"2024-10-12T06:57:22.000Z","size":1823,"stargazers_count":2601,"open_issues_count":18,"forks_count":92,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-04-30T12:16:50.056Z","etag":null,"topics":["chatgpt","cli"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npiv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-19T21:14:16.000Z","updated_at":"2025-04-28T16:56:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"084606e8-79a6-4ed5-b041-813fb932d103","html_url":"https://github.com/npiv/chatblade","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npiv%2Fchatblade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npiv%2Fchatblade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npiv%2Fchatblade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npiv%2Fchatblade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npiv","download_url":"https://codeload.github.com/npiv/chatblade/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190365,"owners_count":22029629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatgpt","cli"],"created_at":"2024-07-30T20:00:50.206Z","updated_at":"2025-05-14T17:02:28.954Z","avatar_url":"https://github.com/npiv.png","language":"Python","readme":"# Chatblade\n\n## A CLI Swiss Army Knife for ChatGPT\n\nChatblade is a versatile command-line interface (CLI) tool designed to interact with OpenAI's ChatGPT. It accepts piped input, arguments, or both, and allows you to save common prompt preambles for quick usage. Additionally, Chatblade provides utility methods to extract JSON or Markdown from ChatGPT responses.\n\n**Note**: You'll need to set up your OpenAI API key to use Chatblade.\n\nYou can do that by either passing `--openai-api-key KEY` or by setting an env variable `OPENAI_API_KEY` (recommended). The examples below all assume an env variable is set.\n\n## Install\n\n### Latest and greatest\n\nTo stay up to date with the current main branch you can:\n\n- check out the project, and run `pip install .`\n- or `pip install 'chatblade @ git+https://github.com/npiv/chatblade'`\n\n### Via pypi\n\nThe last released version can be installed with `pip install chatblade --upgrade`\n\n### Via Brew\n\n```\nbrew install chatblade\n```\n\n## Documentation\n\n### Making queries\n\n#### A new conversation\n\nYou can begin any query by just typing. f.e.:\n\n```bash\nchatblade how can I extract a still frame from a video at 22:01 with ffmpeg\n```\n\n\u003cimg width=\"650\" alt=\"image\" src=\"https://user-images.githubusercontent.com/452020/226869260-1dcd4faf-521c-466b-998a-fd5cfdc5b3c7.png\"\u003e\n\n#### recall the last conversation\n\nif you would like to recall the last conversation just call it back with `-l`\n\n```bash\nchatblade -l\n```\n\n#### Continue the last conversation\n\nTo continue the conversation and ask for a change within the context, you can again use `-l` but with a query.\n\n```bash\nchatblade -l can we make a gif instead from 00:22:01 to 00:22:04\n```\n\n`-l` is shorthand for `-S last` or the last session. We can keep track of and continue various distinct conversations using the [session options](#session-options)\n\n#### Picking between gpt-3.5 and 4\n\nBy default, gpt-3.5 is used, you can switch at any point to 4 by using `-c 4` or the latest 4o (\"omni\") by using `-c 4o`.\n\nAdditionally, you can pass any arbitrary full model name, f.e. `-c gpt-3.5-turbo-16k`.\n\n#### Chatting interactively\n\nIf you preferred to chat interactively instead just use `chatblade -i`.\n\n#### Show streaming text (experimental)\n\nYou can also stream the responses, just like in the webui. At the end of the stream it will format the result. This can be combined in an interactive session\n\n```chatblade -s -i```\n\n\u003chttps://user-images.githubusercontent.com/452020/226891636-54d12df2-528f-4365-a4f3-e51cb025773c.mov\u003e\n\n### Formatting the results\n\nResponses are parsed and if chatblade thinks its markdown it will be presented as such, to get syntax highlighting. But sometimes this may not be what you want, as it removes new lines, or because you are only interested in extracting a part of the result to pipe to another command.\n\nIn that case you have 2 options:\n\n- `-r` for raw, which just prints the text exactly as ChatGPT returned it, and doesn't pass it through Markdown.\n- `-e` for extract, which will try to detect what was returned (either a code block or json) and extract only that part. If neither of those are found it does the same as `-r`\n\nBoth options can be used either with a new query, e.g.\n\n```bash\nchatblade -e write me a python boilerplate script that starts a server and prints hello world \u003e main.py\n```\n\nor with the last result (json in this example)\n\n```bash\nchatblade -l -e | jq\n```\n\n### Piping content into chatblade\n\nIf we have long prompts we don't want to type everytime, or just want to provide context for our query we can pipe into chatblade.\n\ne.g.\n\n```bash\ncurl https://news.ycombinator.com/rss | chatblade given the above rss can you show me the top 3 articles about AI and their links -c 4\n```\n\nThe piped input is placed above the query and sent to ChatGPT.\n\n\u003cimg src=\"assets/example3.png\"\u003e\n\nor\n\n```bash\nchatblade what does this script do \u003c script.sh\n```\n\nWhat gets sent to ChatGPT over the wire is:\n\n```\npiped input\n-------\nquery\n```\n\n#### Session Options\n\nSessions are named conversations.\n\nIf you start chatblade with a session name SESS of your choice:\n\n```bash\nchatblade -S SESS can we make a gif instead from 00:22:01 to 00:22:04\n```\n\nchatblade will create a session called SESS if it does not exist, and it will store the current exchange (query-response pair) for SESS.\n\nIf such a session already exists, the saved conversation will be loaded and the new exchange will be appended.\n\nWithout a session argument, the exchange also gets stored in a session named `last`; however, subsequent sessionless invocation will overwrite the content of `last`. (You can continue a conversation that was started as a sessionless exchange by passing `-S last`, but `last` won't be a safe space for keeping a conversation, as the next sessionless invocation will clear it again.) The `-l` option is provided as a shorthand for `-S last`.\n\nIf you specify a session without a query:\n\n```bash\nchatblade -S SESS\n```\n\nchatblade will recall the conversation without modifying the session.\n\nchatblade supports various operations on sessions. It provides the `--session-OP` options, where `OP` can be `list`, `path`, `dump`, `delete`, `rename`.\n\n### Checking token count and estimated costs\n\nIf you want to check the approximate cost and token usage of a previous query, you can use the `-t` flag for \"tokens.\"\n\nWe could do this when passing in a lot of context like in the example above for instance.\n\n```bash\ncurl https://news.ycombinator.com/rss | chatblade given the above rss can you show me the top 3 articles about AI and their links -t\n```\n\n\u003cimg width=\"650\" alt=\"image\" src=\"https://user-images.githubusercontent.com/452020/226874588-28c53f53-1d19-4ce3-b7ec-b01c2f7cf75a.png\"\u003e\n\nThis won't perform any action over the wire, and just calculates the tokens locally.\n\n### Use custom prompts (the system msg)\n\nThe system message is used to instruct the model how to behave, see [OpenAI - Instructing Chat Models](https://platform.openai.com/docs/guides/chat/instructing-chat-models).\n\nThese can be loaded with `-p`. For convenience any file we place under ~/.config/chatblade/ will be picked up by this command.\n\nSo for example, given the following file `~/.config/chatblade/etymology`, which contains:\n\n```\nI want you to act as a professional Etymologist and Quiz Generator. You have a deep knowledge of etymology and will be provided with a word.\nThe goal is to create cards that quiz on both the etymology and finding the word by its definition.\n\nThe following is what a perfect answer would look like for the word \"disparage\":\n\n[{\n  \"question\": \"A verb used to indicate the act of speaking about someone or something in a negative or belittling way.\u003cbr/\u003e \u003ci\u003eE.g He would often _______ his coworkers behind their backs.\u003c/i\u003e\",\n  \"answer\": \"disparage\"\n},\n{\n  \"question\": \"What is the etymological root of the word disparage?\",\n  \"answer\": \"From the Old French word \u003ci\u003e'desparagier'\u003c/i\u003e, meaning 'marry someone of unequal rank', which comes from \u003ci\u003e'des-'\u003c/i\u003e (dis-) and \u003ci\u003e'parage'\u003c/i\u003e (equal rank)\"\n}]\n\nYou will return answers in JSON only. Answer truthfully and if you don't know then say so. Keep questions as close as possible to the\nprovided examples. Make sure to include an example in the definition question. Use HTML within the strings to nicely format your answers.\n\nIf multiple words are provided, create questions and answers for each of them in one list.\n\nOnly answer in JSON, don't provide any more text. Valid JSON uses \"\" quotes to wrap its items.\n```\n\nWe can now run a command and refer to this prompt with `-p etymology`:\n\n```bash\nchatblade -p etymology gregarious\n```\n\nYou can also point -p to a file path directly to load a system message from any arbitrary location\n\n\u003cimg src=\"assets/example5.png\"\u003e\n\nAnd since we asked for JSON, we can pipe our result to something else, e.g.:\n\n```bash\nchatblade -l -e \u003e toanki\n```\n\n### Configuring for Azure OpenAI\n\nchatblade can be used with an Azure OpenAI endpoint, in which case in addition to the `OPENAI_API_KEY` you'll need to set the following environment variables:\n\n- `OPENAI_API_TYPE` :: Set to `azure`. As required by [openai-python](https://github.com/openai/openai-python)\n- `AZURE_OPENAI_ENDPOINT` :: URL to your cognitive services' endpoint, e.g. `https://eastus.api.cognitive.microsoft.com/`. Please note this is a *breaking change* introduced by `openai-python` and the previous environment variable name is `OPENAI_API_BASE`\n- `OPENAI_API_AZURE_ENGINE` :: name of your deployment in Azure, f.e. `my-gpt-35-turbo` (maps to a specific model)\n\n*Note*: that this will override any option for `-c 3.5` or `-c 4` which don't make sense in this case.\n\n### Help\n\n```\nusage: Chatblade [-h] [--openai-api-key key] [--openai-base-url key] [--temperature t] [-c CHAT_GPT] [-i] [-s] [-t] [--version] [-p name] [-e] [-r] [-n] [-o] [--theme theme] [-l]\n                 [-S sess] [--session-list] [--session-path] [--session-dump] [--session-delete] [--session-rename newsess]\n                 [query ...]\n\na CLI Swiss Army Knife for ChatGPT\n\npositional arguments:\n  query                            Query to send to chat GPT\n\noptions:\n  -h, --help                       show this help message and exit\n  --openai-api-key key             the OpenAI API key can also be set as env variable OPENAI_API_KEY\n  --openai-base-url key            A custom url to use the openAI against a local or custom model, eg ollama\n  --temperature t                  temperature (openai setting)\n  -c CHAT_GPT, --chat-gpt CHAT_GPT\n                                   chat GPT model use either the fully qualified model name, or 3.5 (gpt-3.5-turbo), 4 (gpt-4), 4t (gpt-4-turbo), 4o (gpt-4o), mini (gpt-4o-mini),\n                                   o1 (o1-preview), o1mini (o1-mini). Can also be set via env variable OPENAI_API_MODEL\n  -i, --interactive                start an interactive chat session. This will implicitly continue the conversation\n  -s, --stream                     Stream the incoming text to the terminal\n  -t, --tokens                     display what *would* be sent, how many tokens, and estimated costs\n  --version                        display the chatblade version\n  -p name, --prompt-file name      prompt name - will load the prompt with that name at ~/.config/chatblade/name or a path to a file\n\nresult formatting options:\n  -e, --extract                    extract content from response if possible (either json or code block)\n  -r, --raw                        print session as pure text, don't pretty print or format\n  -n, --no-format                  do not add pretty print formatting to output\n  -o, --only                       Only display the response, omit query\n  --theme theme                    Set the theme for syntax highlighting see https://pygments.org/styles/, can also be set with CHATBLADE_THEME\n\nsession options:\n  -l, --last                       alias for '-S last', the default session if none is specified\n  -S sess, --session sess          initiate or continue named session\n  --session-list                   list sessions\n  --session-path                   show path to session file\n  --session-dump                   dump session to stdout\n  --session-delete                 delete session\n  --session-rename newsess         rename session\n```\n\n","funding_links":[],"categories":["\u003ca name=\"ai\"\u003e\u003c/a\u003eAI / ChatGPT","Python","CLIs","Chat UIs","UIs"],"sub_categories":["Command-line(shell) interface"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpiv%2Fchatblade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpiv%2Fchatblade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpiv%2Fchatblade/lists"}