{"id":26232550,"url":"https://github.com/bulletmark/wordle-aid","last_synced_at":"2025-04-22T10:41:08.626Z","repository":{"id":55614181,"uuid":"456014700","full_name":"bulletmark/wordle-aid","owner":"bulletmark","description":"CLI program to filter word choices to aid solving Wordle game problems","archived":false,"fork":false,"pushed_at":"2025-02-02T04:50:18.000Z","size":2337,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-12T12:06:11.525Z","etag":null,"topics":["wordle","wordle-assistant","wordle-solver"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bulletmark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-02-05T23:55:04.000Z","updated_at":"2025-02-02T04:50:21.000Z","dependencies_parsed_at":"2025-01-28T00:22:07.436Z","dependency_job_id":"e8166375-b492-4566-a8c6-13ddce62014d","html_url":"https://github.com/bulletmark/wordle-aid","commit_stats":{"total_commits":25,"total_committers":1,"mean_commits":25.0,"dds":0.0,"last_synced_commit":"c812a79e6c9ec2e251b21f1c0e10b82a74503145"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fwordle-aid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fwordle-aid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fwordle-aid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletmark%2Fwordle-aid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bulletmark","download_url":"https://codeload.github.com/bulletmark/wordle-aid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243318778,"owners_count":20272136,"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":["wordle","wordle-assistant","wordle-solver"],"created_at":"2025-03-13T00:37:28.617Z","updated_at":"2025-03-13T00:37:29.154Z","avatar_url":"https://github.com/bulletmark.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## WORDLE-AID\n[![PyPi](https://img.shields.io/pypi/v/wordle-aid)](https://pypi.org/project/wordle-aid/)\n[![AUR](https://img.shields.io/aur/version/wordle-aid)](https://aur.archlinux.org/packages/wordle-aid/)\n\n[wordle-aid](http://github.com/bulletmark/wordle-aid) is a Linux command\nline program to filter word choices to aid solving\n[Wordle](https://www.powerlanguage.co.uk/wordle/) problems. You run this\nprogram specifying your previous guesses and results, and then the\nprogram outputs a list of candidate words in English frequency usage\norder to your terminal. Wordle-aid uses the\n[pyspellchecker](https://pyspellchecker.readthedocs.io/en/latest/#)\npackage for its source of English dictionary words and frequencies.\n\nThe following example Wordle (#21) solution illustrates how to use it.\n\n![wordle solution](https://github.com/bulletmark/wordle-aid/raw/main/wordle-example.png)\n\n1. Choose any starting word as normal. You can even use `wordle-aid` to\n   help with this, e.g.\n\n    ```\n    # print all 5 letter words, in reverse frequency order to screen:\n    $ wordle-aid .....\n\n    # Or, print all 5 letter words with at least 3 vowels:\n    $ wordle-aid -v3 .....\n\n    # Or, print all 5 letter words with at least 3 vowels and all unique letters:\n    $ wordle-aid -v3 -u .....\n    ```\n\n2. We choose our favorite starting word **TRACE** as the first guess,\n   which gives the result shown on the first line of the image above.\n   Based on this result, run:\n\n    ```\n    $ wordle-aid TracE ..a..\n    neath 55\n    keats 57\n    yeats 148\n    beaut 168\n    exalt 352\n    leant 380\n    heath 467\n    meaty 726\n    meats 1028\n    feats 1189\n    heats 1539\n    yeast 1587\n    leapt 1884\n    feast 12436\n    seats 18355\n    dealt 19971\n    beast 22995\n    beats 31332\n    meant 212776\n    death 285290\n    least 456376\n    ```\n\n   The output above is the list of possible candidate words, given the\n   command line word arguments you have specified.\n\n   Note: Specify the 1st guess word you used and set each yellow (i.e.\n   correct but incorrect position) letter to upper-case, and other\n   letters to lower-case. Specify all green (i.e. correct and in\n   position) letters you have found so far in the right (wildcard) field\n   in their correct position.\n\n3. Choose a word from the suggestion list output from above command. We\n   choose to enter the highest frequency candidate **LEAST** from the\n   list, which gives the result shown on the second line in the\n   image above. Then run:\n\n    ```\n    $ wordle-aid TracE leasT .ea..\n    neath 55\n    heath 467\n    meaty 726\n    death 285290\n    ```\n\n4. Choose a word from the suggestion list output from the above command.\n   We choose to enter the highest frequency result **DEATH**, which\n   gives us the final correct answer.\n\nIn summary, specify `.....` (all wildcards) as your starting result and\ninsert characters to it as your find them, i.e. all green letters from\neach guess. Note that the number of wildcard characters determines the\nWordle game word size (e.g. `wordle-aid bundle ......` for a 6 letter\ngame). Specify your previous word guesses earlier on the command line.\nThey don't actually have to be in the order that you guessed them\nalthough likely you will be re-editing from your command history so they\nwill be. Yellow letter guesses (i.e. letter valid but in incorrect\nplace) are entered as upper case, and dark/grey letter guesses (i.e.\nletter not present anywhere) are entered as lower case. Green letters\n(i.e. letter valid and in correct place) can be lower or upper case in\nthe earlier word arguments, but **must** be specified in the final\nwildcard word (as either lower or upper case) .\n\n## Example Minimal Solver\n\nWordle-aid also includes an example solver, invoked by the `-s/--solve`\noption to solve in the mininum number of steps assuming the most\nfrequent candidate word is chosen each step. E.g to see an example\nsolution for the above word **DEATH**:\n\n```\n$ wordle-aid -s death\n1 about [AbouT .....]\n2 thank [THank ..a..]\n3 death [death death] SOLVED\n```\n\nYou can also specify 1 or more starting words, e.g if we start with the\nsame word **TRACE** as we chose for the opening example above then we\nget the same sequence of word candidates as the example (because\nwordle-aid selects the highest frequency candidate each step as we\nmanually did in the example).\n\n```\n$ wordle-aid -s trace death\n1 trace [TracE ..a..]\n2 least [leasT .ea..]\n3 death [death death] SOLVED\n```\n\nOr, use a different second word for the example:\n\n```\n$ wordle-aid -s trace stamp death\n1 trace [TracE ..a..]\n2 stamp [sTamp ..a..]\n3 death [death death] SOLVED\n```\n\nBut default, unless you have specified a word for a step, wordle-aid\nselects the highest frequency word candidate each solver iteration. To\nintroduce some randomness, you can instead tell wordle-aid to randomly\nchoose a candidate from within the top N candidates by including the\n`-r/--random` option, e.g:\n\n```\n$ wordle-aid -s -r20 death\n1 right [rigHT .....]\n2 hates [HATEs .....]\n3 teach [Teach .ea.h]\n4 neath [neath .eath]\n5 death [death death] SOLVED\n```\n\nOr from the top N percentage of candidates:\n\n```\n$ wordle-aid -s -r20% death\n1 bonus [bonus .....]\n2 cigar [cigAr .....]\n3 taped [TApED .....]\n4 death [death death] SOLVED\n```\n\n## Simple Python API\n\nThis program takes command line options and arguments and then writes to\nstandard output. If you instead want to run it programmatically from\nanother calling python program (e.g. for a simulation/test) then you can\nimport and run it as a module. The main code is wrapped within a\nfunction signature:\n\n```python\ndef run(args: Union[List[str], str], fp: TextIO = sys.stdout, *,\n        read_start_options: bool = False) -\u003e None\n```\n\nSo you provide a list of option/argument strings (or a single command\nline string) and pass in a string buffer which the program will write to\ninstead of standard output. E.g, as a simple example:\n\n```python\n#!/usr/bin/python3\nimport io\nimport wordle_aid\n\nbuf = io.StringIO()\nwordle_aid.run('-v4 .....', buf)\ntopword = buf.getvalue().splitlines()[-1]\n\n# Output top frequency 5 letter word which has 4 vowels:\nprint(topword.split()[0])\n```\n\nA real example is [this\nscript](https://github.com/bulletmark/wordle-aid/blob/main/wordle-test)\nto automatically solve a list of words and calculate the average number\nof guesses.\n\n## Installation or Upgrade\n\nWordle-aid runs on pure Python and requires the\n[pyspellchecker](https://pyspellchecker.readthedocs.io/en/latest/#) 3rd\nparty package.\n\nArch users can install [wordle-aid from the\nAUR](https://aur.archlinux.org/packages/wordle-aid/).\n\nPython 3.7 or later is required. Note [wordle-aid is on\nPyPI](https://pypi.org/project/wordle-aid/) so just ensure that\n[`pipx`](https://pypa.github.io/pipx/) is installed then type the\nfollowing:\n\n```\n$ pipx install wordle-aid\n```\n\nTo upgrade:\n\n```\n$ pipx upgrade wordle-aid\n```\n\n## Command Line Options\n\nType `wordle-aid -h` to view the usage summary:\n\n```\nusage: wordle-aid [-h] [-l LANGUAGE] [-v VOWELS] [-u] [-w WORDS_FILE]\n                     [-e EXCLUDE_WORDS_FILE] [-s] [-r RANDOM] [-c] [-V]\n                     [words ...]\n\nCLI program to filter word choices to aid solving Wordle game problems.\n\npositional arguments:\n  words                 list of attempted words. Upper case letter is right\n                        letter but wrong place. Lower case letter is wrong\n                        letter anywhere. Last word is wildcards for current\n                        matches.\n\noptions:\n  -h, --help            show this help message and exit\n  -l LANGUAGE, --language LANGUAGE\n                        pyspellchecker language dictionary to use,\n                        default=\"en\"\n  -v VOWELS, --vowels VOWELS\n                        exclude words with less than this number of unique\n                        vowels\n  -u, --unique          exclude words with non-unique letters\n  -w WORDS_FILE, --words-file WORDS_FILE\n                        filter dictionary to words in given text file. Use\n                        multiple times to specify multiple files.\n  -e EXCLUDE_WORDS_FILE, --exclude-words-file EXCLUDE_WORDS_FILE\n                        exclude words in given text file. Use multiple times\n                        to specify multiple files.\n  -s, --solve           solve to final given word, starting with earlier given\n                        words (if any)\n  -r RANDOM, --random RANDOM\n                        choose word for solver at each step randomly from\n                        given number (or %) of top candidates, default=1\n  -c, --no-colors       don't show colors in solver output\n  -V, --version         show wordle-aid version\n\nNote you can set default starting options in \"$HOME/.config/wordle-aid-\nflags.conf\".\n```\n\n## License\n\nCopyright (C) 2022 Mark Blakeney. This program is distributed under the\nterms of the GNU General Public License.\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 3 of the License, or any later\nversion.\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License at \u003chttp://www.gnu.org/licenses/\u003e for more details.\n\n\u003c!-- vim: se ai syn=markdown: --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Fwordle-aid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbulletmark%2Fwordle-aid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletmark%2Fwordle-aid/lists"}