{"id":23971422,"url":"https://github.com/serwy/shellctx","last_synced_at":"2026-05-16T00:02:33.913Z","repository":{"id":44935043,"uuid":"275272687","full_name":"serwy/shellctx","owner":"serwy","description":"shell context helper for saving, recalling, and executing information from a persistent dictionary.","archived":false,"fork":false,"pushed_at":"2022-01-18T03:44:18.000Z","size":125,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-19T09:17:23.257Z","etag":null,"topics":["dictionary","environment-variables","shell","variables"],"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/serwy.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}},"created_at":"2020-06-27T00:35:37.000Z","updated_at":"2022-02-01T00:31:19.000Z","dependencies_parsed_at":"2022-09-04T22:32:16.681Z","dependency_job_id":null,"html_url":"https://github.com/serwy/shellctx","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serwy%2Fshellctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serwy%2Fshellctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serwy%2Fshellctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serwy%2Fshellctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serwy","download_url":"https://codeload.github.com/serwy/shellctx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240501242,"owners_count":19811574,"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":["dictionary","environment-variables","shell","variables"],"created_at":"2025-01-07T03:01:06.793Z","updated_at":"2026-05-16T00:02:28.872Z","avatar_url":"https://github.com/serwy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# shellctx\n\nShell context helper for saving, recalling, and executing information from\na persistent dictionary.\n\n\n## Motivation\n\nSetting environment variables and aliases (`.bashrc`, `.cshrc`, etc.)\nis useful when you have an established workflow with known common actions.\nThis program is for discovering what that workflow should be, when the needed\nworking directories and commands are not fully known just yet. All shell\ninstances have access to the work-in-progress context dictionary.\n\n\n## Usage\n\nThe `ctx` command is the entry into the program. It behaves like a dictionary\nthat can get/set/delete keys and values.\n\n    $ ctx set x 123\n    $ ctx get x\n    123\n\n    $ ctx del x\n\nIt can be used for storing a long directory for later use:\n\n    $ cd /very/long/directory/to/type/manually\n    $ ctx set project `pwd`\n\n    $ cd \"`ctx get project`\"\n\nIt can store long commands for later use:\n\n    $ ctx set server '/usr/bin/python3 -m http.server'\n    $ ctx shell server\n    Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...\n\n\nIt can also save and load environment variables:\n\n    $ ctx set mypath $PATH\n    $ export PATH=\"`ctx get mypath`\"\n\nBy default, `ctx` shows the current context dictionary and the\nsorted timestamped (newest on top) entries:\n\n    $ ctx\n    Using context main\n    There are 2 entries.\n\n    2020-01-01T23:24:40.893719    server = python3 -m http.server\n    2020-01-01T23:07:57.792251    home = /home/serwy\n\n\n## Available Commands\n\n`copy` - copies a key, updates timestamp\n\n    $ ctx copy home home2\n\n`rename` - renames a key, preserves timestamp\n\n    $ ctx rename home2 home3\n\n`items` - provides a sort-by-timestamp display of key-values\n\n    $ ctx items\n    home=/home/serwy\n    server=python3 -m http.server\n\n`keys` - provides a list of keys\n\n    $ ctx keys\n    home\n    server\n\n`log` - print out a log of changes to the context dictionary\n\n    $ ctx log\n    ['2020-01-01T22:51:50.180685', 'set', 'home', '/home/serwy']\n    ['2020-01-01T22:52:01.008981', 'copy', 'home', 'home2']\n    ['2020-01-01T22:52:08.194826', 'rename', 'home2', 'home3']\n\n\n`switch` - switch the context dictionary, or print a list.\nNew contexts may be created this way.\nThe context dictionary can be chained together using '+' and will show a\nmerged dictionary, with changes applied to the first name.\n\n    $ ctx switch dev\n    switching to \"dev\" from \"main\"\n\n    $ ctx switch\n    * dev\n      main\n\n    $ ctx switch main+dev\n    switching to \"main+dev\" from \"dev\"\n\n\n`shell` - uses the key as a command, and values are treated as\nadditional keys. The command string is passed to a shell.\n\n    $ ctx set port 9999\n    $ ctx shell server port\n    Serving HTTP on 0.0.0.0 port 9999 (http://0.0.0.0:9999/) ...\n\n`dryshell` - prints the command passed to the shell without executing\n\n    $ ctx dryshell server port\n    dryrun shell command: python3 -m http.server 9999\n\n`exec` - uses the key to get the executable, and the additional arguments\nare passed directly to the executable. This is like an alias.\n\n    $ ctx exec server 9999\n    Serving HTTP on 0.0.0.0 port 9999 (http://0.0.0.0:9999/) ...\n\n`dryexec` - prints the arguments passed to the executable without executing.\n\n    $ ctx dryexec server 9999\n    dryrun exec command: ['python3', '-m', 'http.server', '9999']\n\n`set` - set a key to a value\n\n    $ ctx set keyname value\n\n`get` - print the value for the given key\n\n    $ ctx get server\n    python3 -m http.server\n\n`del` - delete a key\n\n    $ ctx del keyname\n\n`setpath` - add the present working directory to the value when setting\nthe given key\n\n    $ ctx setpath keyname .bashrc\n    keyname=/home/serwy/.bashrc\n\n`args` - print out the arguments as seen by the program, quoted. This\nis useful when debugging argument quoting errors.\n\n    $ ctx args some arguments \"kept together\"\n    sys.argv[:]\n        0 = '/home/serwy/.local/bin/ctx'\n        1 = 'args'\n        2 = 'some'\n        3 = 'arguments'\n        4 = 'kept together'\n\n`entry` - auto-increment the maximum suffix for a key before setting.\nThis is useful for storing quick notes.\n\n    $ ctx entry _note This is an observation\n    _note_001=This is an observation\n\n    $ ctx entry _note system A depends on system B\n    _note_002=system A depends on system B\n\n`now` - prints out the iso8601 time, filesystem safe.\nThis is useful for quickly appending a suffix to a file\n\n    $ ctx now\n    2020-01-01T193048.465660\n\n    $ cp myfile.txt ~/backup/myfile.txt_`ctx now`\n\n`update` - opens a given file for loading `key=value` data. Use a\nhyphen to read from stdin.\n\n    $ ctx switch env\n    $ env | ctx update -\n    $ ctx\n    Using context env\n    There are 6 entries.\n\n    2020-01-01T17:06:10.234052    _ = /usr/bin/env\n    2020-01-01T17:06:10.234040    PATH = /home/serwy/.local/bin:/usr/local/bin:/usr/bin\n    2020-01-01T17:06:10.234038    LC_ALL = en_US.UTF-8\n    2020-01-01T17:06:10.234028    DISPLAY = :0\n    2020-01-01T17:06:10.234012    HOME = /home/serwy\n    2020-01-01T17:06:10.233881    SHELL = /bin/bash\n\n`waitpid` - waits for a PID to finish before exiting, possible displaying a message box.\n\n    # assume PID 5417 is a long-running process\n    $ ctx waitpid 5417 [message]\n\n`message` - displays a graphical message box with a message, along with PID,\nstart time, and window elapsed time.\n\n    $ ctx message Hello World     # Tkinter window appears\n\n\n## Environment Variables\n\n### `CTX_NAME`\n\nThe active context may be forced by setting the `CTX_NAME` environment variable.\n\nThis is useful when needing to dedicate a terminal to a particular context.\n\n### `CTX_VERBOSE`\n\nA flag to increase verbosity. It is an integer value of `0`, `1`, or more.\nIf undefined, it defaults to `0`.\n\n### `CTX_HOME`\n\nSet the directory containing the dictionaries and logs. If unset,\nit defaults to `~/.ctx/`.\n\n## Implementation details\n\nThe context dictionaries are stored in `~/.ctx/`\nThe `.json` files are the context dictionaries.\nThe `.log` files are the change logs.\n\nThe `_name.txt` file contains the name of the active context.\nIf missing, defaults to `main`.\n\n\n## Install\n\nEnsure that the `ctx` script can be found on your system `PATH`,\ne.g. `~/.local/bin`.\n\n    pip3 install shellctx\n\nor\n\n    python3 setup.py install\n\nIf you just want the script directly, you can download and copy\n`shellctx/ctx.py` as `ctx` somewhere on your `$PATH` and apply `chmod +x`.\nThe direct link is: https://raw.githubusercontent.com/serwy/shellctx/latest/shellctx/ctx.py\n\n    curl  https://raw.githubusercontent.com/serwy/shellctx/latest/shellctx/ctx.py \u003e ctx\n    chmod +x ctx\n\n## License\n\nLicensed under the GNU General Public License, Version 3.0\n\n\n## See also\n\n* https://en.wikipedia.org/wiki/ISO_8601\n* https://xkcd.com/1179/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserwy%2Fshellctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserwy%2Fshellctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserwy%2Fshellctx/lists"}