rbcli 0.3.2 → 0.3.3

data/docs/index.json

@@ -4,7 +4,7 @@
 	"title": "Quick Reference",
 	"tags": [],
 	"description": "",
-	"content": "Installation RBCli is available on rubygems.org. You can add it to your application\u0026rsquo;s Gemfile or gemspec, or install it manually by running:\ngem install rbcli Then, cd to the folder you\u0026rsquo;d like to create your project under and run:\nrbcli init -n mytool -d \u0026#34;A simple CLI tool\u0026#34; Or, for a single-file tool without any folder/gem tructure, run rbcli init -t mini -n \u0026lt;projectname\u0026gt; or rbcli init -t micro -n \u0026lt;projectname\u0026gt;.\nCreating a command There are three types of commands: standard, scripted, and external.\n Standard commands let you code the command directly in Ruby Scripted commands provide you with a bash script, where all of the parsed information (params, options, args, and config) is shared External commands let you wrap 3rd party applications directly  Standard Commands To create a new command called foo, run:\nrbcli command -n foo You will now find the command code in application/commands/list.rb. Edit the action block to write your coode.\nScripted Commands To create a new scripted command called bar, run:\nrbcli script -n bar You will then find two new files:\n The command declaration under application/commands/bar.rb The script code under application/commands/scripts/bar.sh  Edit the script to write your code.\nExternal Commands To create a new external command called baz, run:\nrbcli extern -n baz You will then find the command code in application/commands/baz.rb.\nUse one of the two provided modes \u0026ndash; direct path mode or variable path mode \u0026ndash; to provide the path to the external program.\nHooks RBCli has several hooks that run at different points in the exectution chain. They can be created via the rbcli command line tool:\nrbcli hook --default # Runs when no command is provided rbcli hook --pre # Runs before any command rbcli hook --post # Runs after any command rbcli hook --firstrun # Runs the first time a user runs your application. Requires userspace config. rbcli hook -dpof # Create all hooks at once Storage RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.\nLocal State RBCli can provide you with a unique hash that can be persisted to disk on any change to a top-level value.\nEnable local state in config/storage.rb.\nThen access it in your Standard Commands with Rbcli.local_state[:yourkeyhere].\nRemote State Similar to the Local State above, RBCli can provide you with a unique hash that can be persisted to a remote storage location.\nCurrently only AWS DynamoDB is supported, and credentials will be required for each user.\nEnable remote state in config/storage.rb.\nThen access it in your Standard Commands with Rbcli.remote_state[:yourkeyhere].\nUserspace Configuration Files RBCli provides an easy mechanism to generate and read configuration files from your users. You set the default values and help text with the defaults chain, and leverage the user chain to read them.\nYou can set defaults either by placing a YAML file in the userconf/ folder or by specifying individual options in application/options.rb (global) or application/command/*.rb (command-specific).\nUsers can generate a config file, complete with help text, by running your tool with the --generate-config option.\nLogging RBCli\u0026rsquo;s logger is configured in config/logging.rb.\nlog_level :info log_target \u0026#39;stderr\u0026#39; Then it can be accessed when writing your commands via:\nRbcli::log.info { \u0026#39;These logs can go to STDERR, STDOUT, or a file\u0026#39; } The user will also be able to change the log level and target via their config file, if it is enabled.\nAutomatic Update Check RBCli can automatically notify users when an update is available. Two sources are currently supported: Github (including Enterprise) and RubyGems.\nYou can configure automatic updates in config/autoupdate.rb in your project.\nRemote Execution RBCli can automatically execute script and extern commands on remote machines via SSH. Enable this feature in config/general.rb by changing the following line to true:\nremote_execution permitted: false Then for each command you want to enable remote execution for, add the following directive:\nremote_permitted Users can then execute commands remotly by specifying the connection string and credentials on the command line:\nmytool --remote-exec [user@]host[:port] --identity (/path/to/private/ssh/key or password) \u0026lt;command\u0026gt; ... Development and Contributing For more information about development and contributing, please see the Official Development Documentation\nLicense The gem is available as open source under the terms of the GPLv3.\nFull Documentation You can find the Official Documentation for RBCli Here.\n"
+	"content": "Installation RBCli is available on rubygems.org. You can add it to your application\u0026rsquo;s Gemfile or gemspec, or install it manually by running:\ngem install rbcli Then, cd to the folder you\u0026rsquo;d like to create your project under and run:\nrbcli init -n mytool -d \u0026#34;A simple CLI tool\u0026#34; Or, for a single-file tool without any folder/gem tructure, run rbcli init -t mini -n \u0026lt;projectname\u0026gt; or rbcli init -t micro -n \u0026lt;projectname\u0026gt;.\nCreating a command There are three types of commands: standard, scripted, and external.\nStandard commands let you code the command directly in Ruby Scripted commands provide you with a bash script, where all of the parsed information (params, options, args, and config) is shared External commands let you wrap 3rd party applications directly Standard Commands To create a new command called foo, run:\nrbcli command -n foo You will now find the command code in application/commands/list.rb. Edit the action block to write your coode.\nScripted Commands To create a new scripted command called bar, run:\nrbcli script -n bar You will then find two new files:\nThe command declaration under application/commands/bar.rb The script code under application/commands/scripts/bar.sh Edit the script to write your code.\nExternal Commands To create a new external command called baz, run:\nrbcli extern -n baz You will then find the command code in application/commands/baz.rb.\nUse one of the two provided modes \u0026ndash; direct path mode or variable path mode \u0026ndash; to provide the path to the external program.\nHooks RBCli has several hooks that run at different points in the exectution chain. They can be created via the rbcli command line tool:\nrbcli hook --default # Runs when no command is provided rbcli hook --pre # Runs before any command rbcli hook --post # Runs after any command rbcli hook --firstrun # Runs the first time a user runs your application. Requires userspace config. rbcli hook -dpof # Create all hooks at once Storage RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.\nLocal State RBCli can provide you with a unique hash that can be persisted to disk on any change to a top-level value.\nEnable local state in config/storage.rb.\nThen access it in your Standard Commands with Rbcli.local_state[:yourkeyhere].\nRemote State Similar to the Local State above, RBCli can provide you with a unique hash that can be persisted to a remote storage location.\nCurrently only AWS DynamoDB is supported, and credentials will be required for each user.\nEnable remote state in config/storage.rb.\nThen access it in your Standard Commands with Rbcli.remote_state[:yourkeyhere].\nUserspace Configuration Files RBCli provides an easy mechanism to generate and read configuration files from your users. You set the default values and help text with the defaults chain, and leverage the user chain to read them.\nYou can set defaults either by placing a YAML file in the userconf/ folder or by specifying individual options in application/options.rb (global) or application/command/*.rb (command-specific).\nUsers can generate a config file, complete with help text, by running your tool with the --generate-config option.\nLogging RBCli\u0026rsquo;s logger is configured in config/logging.rb.\nlog_level :info log_target \u0026#39;stderr\u0026#39; Then it can be accessed when writing your commands via:\nRbcli::log.info { \u0026#39;These logs can go to STDERR, STDOUT, or a file\u0026#39; } The user will also be able to change the log level and target via their config file, if it is enabled.\nAutomatic Update Check RBCli can automatically notify users when an update is available. Two sources are currently supported: Github (including Enterprise) and RubyGems.\nYou can configure automatic updates in config/autoupdate.rb in your project.\nRemote Execution RBCli can automatically execute script and extern commands on remote machines via SSH. Enable this feature in config/general.rb by changing the following line to true:\nremote_execution permitted: false Then for each command you want to enable remote execution for, add the following directive:\nremote_permitted Users can then execute commands remotly by specifying the connection string and credentials on the command line:\nmytool --remote-exec [user@]host[:port] --identity (/path/to/private/ssh/key or password) \u0026lt;command\u0026gt; ... Development and Contributing For more information about development and contributing, please see the Official Development Documentation\nLicense The gem is available as open source under the terms of the GPLv3.\nFull Documentation You can find the Official Documentation for RBCli Here.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/tutorial/",
@@ -18,7 +18,7 @@
 	"title": "Contribution Guide",
 	"tags": [],
 	"description": "",
-	"content": "Contributing to RBCli is the same as most open source projects:\n Fork the repository Create your own branch Submit a pull request when ready  That\u0026rsquo;s all there is to it! We\u0026rsquo;ve also kept our acceptance criteria pretty simple, as you\u0026rsquo;ll see below. Feel free to submit a pull request even if you don\u0026rsquo;t meet it if you would like your code or feature to be reviewed first; we do want to be mindful of your time and will review submissions before they are polished.\nDevelpment Mode To allow for easy deveopment, Rbcli has a development mode which allows a project to include rbcli from a local folder instead of the default gem path. To use it, add the following to your shell\u0026rsquo;s profile (typically ~/.bash_profile or ~/.profile):\nexport RBCLI_ENV=\u0026#39;development\u0026#39; export RBCLI_DEVPATH=\u0026#39;/path/to/rbcli/lib/rbcli\u0026#39; alias rbcli=\u0026#39;/path/to/rbcli/exe/rbcli\u0026#39; Code Acceptance Criteria Tabs, Not Spaces Please, and thanks. We all like to use different indentation levels and styles, and this will keep us consistent between editors.\nFor filetypes where tabs are not supported (such as YAML), please stick to using two (2) spaces.\nDocumentation for User Features For any modification that alters the way RBCli is used \u0026ndash; we\u0026rsquo;re talking additional features, options, keyword changes, major behavioral changes, and the like \u0026ndash; the documentation will need to be updated as well. You\u0026rsquo;ll be happy to know we designed it to make the process relatively painless.\nRBCli\u0026rsquo;s documentation is essentially a collection of markdown files that have been compiled into a static site using MkDocs. If you already have python and pip on your system, you can install it by running:\npip install mkdocs mkdocs-material You can find the source markdown files in the docs-src/docs folder, and the menu organization in docs-src/mkdocs.yml. To preview your changes on a live site, run:\nmkdocs serve Also, don\u0026rsquo;t forget to update the Quick Reference Guide in the README.md file (the main project one) with information about your changes.\nOnce you\u0026rsquo;ve completed your edits, run the makesite.sh command to build the actual HTML pages automatically in the docs folder, from where they will be served when live.\nDeprecations If a feature needs to be deprecated, RBCli has a built-in deprecation message feature. You can leverage it by calling the following code when a deprecated command is called:\nRbcli::DeprecationWarning.new deprecated_command, message, version_when_code_will_be_removed So, for example:\nRbcli::DeprecationWarning.new \u0026#39;Rbcli::Configurate.me--first_run\u0026#39;, \u0026#39;Please use `RBCli::Configurate.hooks` as the parent block instead.\u0026#39;, \u0026#39;0.3.0\u0026#39; will display the following message to the user, in red, any any time the application is run:\nDEPRECATION WRNING: The feature `Rbcli::Configurate.me--post_hook` has been deprecated. Please use `RBCli::Configurate.hooks` as the parent block instead. This feature will be removed in version 0.3.0. Additionally, it will place the same line in the logs using Rbcli.logger.warn if logging is enabled.\nIf a deprecation warning has been added, please remember to mention it in the pull request so that others can update it later.\nMaintainer\u0026rsquo;s Notes To install this gem onto your local machine from source, run bundle exec rake install.\nTo release a new version, follow theese steps:\n Update the version number in version.rb Run bundle exec rake install, which will update gemfile.lock with the correct version and all dependency changes Run docs-src/makesite.sh, which re-compiles the documentation and pulls in the changelog and quick reference automatically Commit the above changes to master with a commit message of \u0026ldquo;vX.X.X\u0026rdquo; (where X.X.X is the version number), but do not push Run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.  "
+	"content": "Contributing to RBCli is the same as most open source projects:\nFork the repository Create your own branch Submit a pull request when ready That\u0026rsquo;s all there is to it! We\u0026rsquo;ve also kept our acceptance criteria pretty simple, as you\u0026rsquo;ll see below. Feel free to submit a pull request even if you don\u0026rsquo;t meet it if you would like your code or feature to be reviewed first; we do want to be mindful of your time and will review submissions before they are polished.\nDevelpment Mode To allow for easy deveopment, Rbcli has a development mode which allows a project to include rbcli from a local folder instead of the default gem path. To use it, add the following to your shell\u0026rsquo;s profile (typically ~/.bash_profile or ~/.profile):\nexport RBCLI_ENV=\u0026#39;development\u0026#39; export RBCLI_DEVPATH=\u0026#39;/path/to/rbcli/lib/rbcli\u0026#39; alias rbcli=\u0026#39;/path/to/rbcli/exe/rbcli\u0026#39; Code Acceptance Criteria Tabs, Not Spaces Please, and thanks. We all like to use different indentation levels and styles, and this will keep us consistent between editors.\nFor filetypes where tabs are not supported (such as YAML), please stick to using two (2) spaces.\nDocumentation for User Features For any modification that alters the way RBCli is used \u0026ndash; we\u0026rsquo;re talking additional features, options, keyword changes, major behavioral changes, and the like \u0026ndash; the documentation will need to be updated as well. You\u0026rsquo;ll be happy to know we designed it to make the process relatively painless.\nRBCli\u0026rsquo;s documentation is essentially a collection of markdown files that have been compiled into a static site using MkDocs. If you already have python and pip on your system, you can install it by running:\npip install mkdocs mkdocs-material You can find the source markdown files in the docs-src/docs folder, and the menu organization in docs-src/mkdocs.yml. To preview your changes on a live site, run:\nmkdocs serve Also, don\u0026rsquo;t forget to update the Quick Reference Guide in the README.md file (the main project one) with information about your changes.\nOnce you\u0026rsquo;ve completed your edits, run the makesite.sh command to build the actual HTML pages automatically in the docs folder, from where they will be served when live.\nDeprecations If a feature needs to be deprecated, RBCli has a built-in deprecation message feature. You can leverage it by calling the following code when a deprecated command is called:\nRbcli::DeprecationWarning.new deprecated_command, message, version_when_code_will_be_removed So, for example:\nRbcli::DeprecationWarning.new \u0026#39;Rbcli::Configurate.me--first_run\u0026#39;, \u0026#39;Please use `RBCli::Configurate.hooks` as the parent block instead.\u0026#39;, \u0026#39;0.3.0\u0026#39; will display the following message to the user, in red, any any time the application is run:\nDEPRECATION WRNING: The feature `Rbcli::Configurate.me--post_hook` has been deprecated. Please use `RBCli::Configurate.hooks` as the parent block instead. This feature will be removed in version 0.3.0. Additionally, it will place the same line in the logs using Rbcli.logger.warn if logging is enabled.\nIf a deprecation warning has been added, please remember to mention it in the pull request so that others can update it later.\nMaintainer\u0026rsquo;s Notes To install this gem onto your local machine from source, run bundle exec rake install.\nTo release a new version, follow theese steps:\nUpdate the version number in version.rb Run bundle exec rake install, which will update gemfile.lock with the correct version and all dependency changes Run docs-src/makesite.sh, which re-compiles the documentation and pulls in the changelog and quick reference automatically Commit the above changes to master with a commit message of \u0026ldquo;vX.X.X\u0026rdquo; (where X.X.X is the version number), but do not push Run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org. "
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/tutorial/10-getting_started/",
@@ -46,7 +46,7 @@
 	"title": "The Project Layout",
 	"tags": [],
 	"description": "",
-	"content": "Now we will learn about what an RBCli project looks like and how to start using it.\nProject Initialization Types RBCli can initialize a tool in three different modes:\n Project Mode (default) Mini Mode Micro Mode  Project Mode If you\u0026rsquo;ve been following along with the tutorial, you\u0026rsquo;ve already seen Project Mode. An RBCli Project consists of several folders, each of which has a specific function. The RBCli framework handles loading and parsing the code automatically. To generate a standard, full-featured RBCli project, run:\nrbcli init -n mytool where mytool can be replaced with any other command name you\u0026rsquo;d like. (We will continue using mytool in this tutorial though!)\nInside the newly created mytool folder you will see a bunch of files and folders related to your project. We will go over the structure later.\nMini \u0026amp; Micro Modes If you need to write a CLI tool but project mode feels a bit overkill for you \u0026ndash; if you think a single-file script is all that is needed \u0026ndash; that\u0026rsquo;s where the Mini and Micro modes come in. Instead of generating a full directory tree, you get only a single file that contains most of the functionality of RBCli. To use it, run:\nrbcli init -n mytool -t mini # or rbcli init -n mytool -t micro The only difference between the two is that mini will show you all available options and some documentation to help you, while micro is for advanced users who just want the samllest file possible.\nAs far as documentation goes, every piece of code present in those files is identical to Project mode so it should be pretty easy to navigate.\nProject Mode Structure An RBCli project has the following structure:\n\u0026lt;name\u0026gt;/ |--- application/ | |--- commands/ | | |--- scripts/ | |--- options.rb |--- config/ |--- exe/ | |--- \u0026lt;name\u0026gt; |--- hooks/ |--- lib/ | |--- \u0026lt;name\u0026gt;/ | |--- \u0026lt;name\u0026gt;.rb |--- spec/ |--- userconf/ |--- .gitignore |--- .rbcli |--- .rspec |--- CODE_OF_CONDUCT.md |--- Gemfile |--- README.md |--- Rakefile |--- \u0026lt;name\u0026gt;.gemspec Git, RubyGems, and rspec A few files aren\u0026rsquo;t part of RBCli itself, but are provided for your convenience. If you\u0026rsquo;re experienced in Ruby and Git you can skip over this.\n .gitignore  Specifies which files to ignore in git. If you don\u0026rsquo;t use git you can delete this file   .rspec  Configures Rspec for testing your code   Gemfile  Allows declaring dependencies for when your users install your application   Gemspec  Same as above, but also lets you fill in more information so that you can publish your application as a gem   README.md  A skeleton README file that will appear as a front page documentation to your code in most source control systems (i.e. Github, Bitbucket)   CODE_OF_CONDUCT.md  Taken directly from the contributor covenant for your convenience   Rakefile  So you can run rspec tests as a rake task    There is a lot of controvesy online regarding using the gemfile vs the gemspec. If you are new to Ruby in general then I suggest declaring your dependencies in the gemspec and leaving the gemfile as-is. This keeps things simple and allows publishing and distributing your tool as a gem.\nAdditionally, note that a git repo is not created automatically. Using git is out of scope of this tutorial, but you can find tutorials here.\nRBCli Folders  application/  This is where the core of your application will live. You will define CLI options, commands, scripts, and hooks within this folder.   config/  This folder contains the configuration for RBCli\u0026rsquo;s features; such as storage, logging, and automatic updates.   exe/  This folder contains the executable for your tool. You should not edit it; doing so may lead to unexpected behavior.   hooks/  RBCli has several hooks that can be used to run code at different times, such as the \u0026lsquo;default\u0026rsquo; code that is run when no command is selected. This is where they are placed.   lib/  This folder is for you to write any additional code as you see fit, for importing into your commands, scripts, and hooks. It is automatically added to the $LOAD_PATH for you, so you can just use require statements like require 'abc.rb' without worrying about where they are located on the filesystem.   userconf/  This folder is for you to place the layout and defaults of any userspace config file. Acceptable formats are yaml and json, though we recommend YAML since it is by far easier to read and supports comments.   spec/  This folder is for your rspec tests.   .rbcli  This file is for internal use by RBCli. It should not be modified or deleted.    Next Steps For the purposes of getting started right now, you don\u0026rsquo;t actually need to edit any of the defaults already present.\nWe just finished going through what an RBCli project looks like. Now let\u0026rsquo;s create our first application with it!\n"
+	"content": "Now we will learn about what an RBCli project looks like and how to start using it.\nProject Initialization Types RBCli can initialize a tool in three different modes:\nProject Mode (default) Mini Mode Micro Mode Project Mode If you\u0026rsquo;ve been following along with the tutorial, you\u0026rsquo;ve already seen Project Mode. An RBCli Project consists of several folders, each of which has a specific function. The RBCli framework handles loading and parsing the code automatically. To generate a standard, full-featured RBCli project, run:\nrbcli init -n mytool where mytool can be replaced with any other command name you\u0026rsquo;d like. (We will continue using mytool in this tutorial though!)\nInside the newly created mytool folder you will see a bunch of files and folders related to your project. We will go over the structure later.\nMini \u0026amp; Micro Modes If you need to write a CLI tool but project mode feels a bit overkill for you \u0026ndash; if you think a single-file script is all that is needed \u0026ndash; that\u0026rsquo;s where the Mini and Micro modes come in. Instead of generating a full directory tree, you get only a single file that contains most of the functionality of RBCli. To use it, run:\nrbcli init -n mytool -t mini # or rbcli init -n mytool -t micro The only difference between the two is that mini will show you all available options and some documentation to help you, while micro is for advanced users who just want the samllest file possible.\nAs far as documentation goes, every piece of code present in those files is identical to Project mode so it should be pretty easy to navigate.\nProject Mode Structure An RBCli project has the following structure:\n\u0026lt;name\u0026gt;/ |--- application/ | |--- commands/ | | |--- scripts/ | |--- options.rb |--- config/ |--- exe/ | |--- \u0026lt;name\u0026gt; |--- hooks/ |--- lib/ | |--- \u0026lt;name\u0026gt;/ | |--- \u0026lt;name\u0026gt;.rb |--- spec/ |--- userconf/ |--- .gitignore |--- .rbcli |--- .rspec |--- CODE_OF_CONDUCT.md |--- Gemfile |--- README.md |--- Rakefile |--- \u0026lt;name\u0026gt;.gemspec Git, RubyGems, and rspec A few files aren\u0026rsquo;t part of RBCli itself, but are provided for your convenience. If you\u0026rsquo;re experienced in Ruby and Git you can skip over this.\n.gitignore Specifies which files to ignore in git. If you don\u0026rsquo;t use git you can delete this file .rspec Configures Rspec for testing your code Gemfile Allows declaring dependencies for when your users install your application Gemspec Same as above, but also lets you fill in more information so that you can publish your application as a gem README.md A skeleton README file that will appear as a front page documentation to your code in most source control systems (i.e. Github, Bitbucket) CODE_OF_CONDUCT.md Taken directly from the contributor covenant for your convenience Rakefile So you can run rspec tests as a rake task There is a lot of controvesy online regarding using the gemfile vs the gemspec. If you are new to Ruby in general then I suggest declaring your dependencies in the gemspec and leaving the gemfile as-is. This keeps things simple and allows publishing and distributing your tool as a gem.\nAdditionally, note that a git repo is not created automatically. Using git is out of scope of this tutorial, but you can find tutorials here.\nRBCli Folders application/ This is where the core of your application will live. You will define CLI options, commands, scripts, and hooks within this folder. config/ This folder contains the configuration for RBCli\u0026rsquo;s features; such as storage, logging, and automatic updates. exe/ This folder contains the executable for your tool. You should not edit it; doing so may lead to unexpected behavior. hooks/ RBCli has several hooks that can be used to run code at different times, such as the \u0026lsquo;default\u0026rsquo; code that is run when no command is selected. This is where they are placed. lib/ This folder is for you to write any additional code as you see fit, for importing into your commands, scripts, and hooks. It is automatically added to the $LOAD_PATH for you, so you can just use require statements like require 'abc.rb' without worrying about where they are located on the filesystem. userconf/ This folder is for you to place the layout and defaults of any userspace config file. Acceptable formats are yaml and json, though we recommend YAML since it is by far easier to read and supports comments. spec/ This folder is for your rspec tests. .rbcli This file is for internal use by RBCli. It should not be modified or deleted. Next Steps For the purposes of getting started right now, you don\u0026rsquo;t actually need to edit any of the defaults already present.\nWe just finished going through what an RBCli project looks like. Now let\u0026rsquo;s create our first application with it!\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/development/",
@@ -60,49 +60,49 @@
 	"title": "Code of Conduct",
 	"tags": [],
 	"description": "",
-	"content": "The Contributor Covenant Code of Conduct\nOur Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.\nOur Standards Examples of behavior that contributes to creating a positive environment include:\n Using welcoming and inclusive language Being respectful of differing viewpoints and experiences Gracefully accepting constructive criticism Focusing on what is best for the community Showing empathy towards other community members  Examples of unacceptable behavior by participants include:\n The use of sexualized language or imagery and unwelcome sexual attention or advances Trolling, insulting/derogatory comments, and personal or political attacks Public or private harassment Publishing others' private information, such as a physical or electronic address, without explicit permission Other conduct which could reasonably be considered inappropriate in a professional setting  Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\nScope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\nEnforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at andrew@blacknex.us. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project\u0026rsquo;s leadership.\nAttribution This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4\n"
+	"content": "The Contributor Covenant Code of Conduct\nOur Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.\nOur Standards Examples of behavior that contributes to creating a positive environment include:\nUsing welcoming and inclusive language Being respectful of differing viewpoints and experiences Gracefully accepting constructive criticism Focusing on what is best for the community Showing empathy towards other community members Examples of unacceptable behavior by participants include:\nThe use of sexualized language or imagery and unwelcome sexual attention or advances Trolling, insulting/derogatory comments, and personal or political attacks Public or private harassment Publishing others\u0026rsquo; private information, such as a physical or electronic address, without explicit permission Other conduct which could reasonably be considered inappropriate in a professional setting Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\nScope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\nEnforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at andrew@blacknex.us. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project\u0026rsquo;s leadership.\nAttribution This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/tutorial/30-your_first_command/",
 	"title": "Your First Command",
 	"tags": [],
 	"description": "",
-	"content": "Creating the Command Creating the command is straightforward:\nrbcli command --name=list #or rbcli command -n list And there you have it! Now you can try out your command by typing:\n./exe/mytool list Congrats! You should now see a generic output listing the values of several variables. We\u0026rsquo;ll get into what they mean in a bit, but first, let\u0026rsquo;s make the tool\u0026rsquo;s execution a bit easier.\nNow that you know your way around a project, its time to create your first command! But before we do, let\u0026rsquo;s make development just a little bit easier. Go to the base directory of the folder and type:\nalias mytool=\u0026#34;$(pwd)/exe/mytool\u0026#34; And now you\u0026rsquo;ll be able to execute your application as if it was already installed as a gem, without worrying about the working path. You can see this in action by running your application again, but without the path:\nmytool list So, now let\u0026rsquo;s take a more in-dpeth look at what the command code looks like.\nThe Command Declaration As mentioned in the previous section, you can find your commands listed under the application/commands/ directory. Each command will appear as its own unique file with some base code to work from. Let\u0026rsquo;s take a look at that code a little more in-depth:\nclass List \u0026lt; Rbcli::Command # Declare a new command by subclassing Rbcli::Command description \u0026#39;TODO: Description goes here\u0026#39; # (Required) Short description for the global help usage \u0026lt;\u0026lt;-EOF TODO: Usage text goes here EOF # (Required) Long description for the command-specific help parameter :force, \u0026#39;Force testing\u0026#39;, type: :boolean, default: false, required: false # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times config_default :myopt2, description: \u0026#39;My Option #2\u0026#39;, default: \u0026#39;Default Value Here\u0026#39; # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config. # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options action do |params, args, global_opts, config| # (Required) Block to execute if the command is called. Rbcli::log.info { \u0026#39;These logs can go to STDERR, STDOUT, or a file\u0026#39; } # Example log. Interface is identical to Ruby\u0026#39;s logger puts \u0026#34;\\nArgs:\\n#{args}\u0026#34; # Arguments that came after the command on the CLI (i.e.: `mytool test bar baz` will yield args=[\u0026#39;bar\u0026#39;, \u0026#39;baz\u0026#39;]) puts \u0026#34;Params:\\n#{params}\u0026#34; # Parameters, as described through the option statements above puts \u0026#34;Global opts:\\n#{global_opts}\u0026#34; # Global Parameters, as descirbed in the Configurate section puts \u0026#34;Config:\\n#{config}\u0026#34; # Config file values puts \u0026#34;LocalState:\\n#{Rbcli.local_state}\u0026#34; # Local persistent state storage (when available) -- if unsure use Rbcli.local_state.nil? puts \u0026#34;RemoteState:\\n#{Rbcli.remote_state}\u0026#34; # Remote persistent state storage (when available) -- if unsure use Rbcli.remote_state.nil? puts \u0026#34;\\nDone!!!\u0026#34; end end Commands are declared to RBCli simply by subclassing them from Rbcli::Command as shown above. Then, you have a list of declarations that tell RBCli information about it. They are:\n description  A short description of the command, which will appear in the top-level help (when the user runs mytool -h).   usage  A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you\u0026rsquo;d like. It will show up as a long, multi-line description when the user runs the command-sepcific help (mytool list -h).   parameter  Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on Options, Parameters, and Arguments   config_default  This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on User Config Files   action  This loads the block of code that will run when the command is called. It brings in all of the CLI and user config data as variables. We will also get into these in the next section Options, Parameters, and Arguments    There is an additional declaration not shown here, extern. You can find more information on it in the section on Advanced Command Types\nCreating the \u0026ldquo;list\u0026rdquo; Command Now we\u0026rsquo;re going to modify this command to list the contents of the current directory to the terminal. So let\u0026rsquo;s change the code in that file to:\nclass List \u0026lt; Rbcli::Command description %q{List files in current directory} usage \u0026lt;\u0026lt;-EOF Ever wanted to see your files? Now you can! EOF action do |params, args, global_opts, config| filelist = [] # We store a list of the files in an array, including dotfiles if specified Dir.glob \u0026#34;./*\u0026#34; do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] outname += \u0026#39;/\u0026#39; if File.directory? filename filelist.append outname end # Apply color filelist.map! do |filename| if File.directory? filename filename.light_blue elsif File.executable? filename filename.light_green else filename end end if global_opts[:color] puts filelist end end Go ahead and test it out! The output doesn\u0026rsquo;t show much obviously, just a list of names and nothing else. Don\u0026rsquo;t worry though, we\u0026rsquo;ll fix that in the next secion.\nNext Steps Next we\u0026rsquo;re going to take a look at options, parameters, and arguments, and we\u0026rsquo;ll clean up our list command by using them. If you\u0026rsquo;d like to learn more about the additional command types in RBCli before continuing, see the Advanced Command Types documentation.\n"
+	"content": "Creating the Command Creating the command is straightforward:\nrbcli command --name=list #or rbcli command -n list And there you have it! Now you can try out your command by typing:\n./exe/mytool list Congrats! You should now see a generic output listing the values of several variables. We\u0026rsquo;ll get into what they mean in a bit, but first, let\u0026rsquo;s make the tool\u0026rsquo;s execution a bit easier.\nNow that you know your way around a project, its time to create your first command! But before we do, let\u0026rsquo;s make development just a little bit easier. Go to the base directory of the folder and type:\nalias mytool=\u0026#34;$(pwd)/exe/mytool\u0026#34; And now you\u0026rsquo;ll be able to execute your application as if it was already installed as a gem, without worrying about the working path. You can see this in action by running your application again, but without the path:\nmytool list So, now let\u0026rsquo;s take a more in-dpeth look at what the command code looks like.\nThe Command Declaration As mentioned in the previous section, you can find your commands listed under the application/commands/ directory. Each command will appear as its own unique file with some base code to work from. Let\u0026rsquo;s take a look at that code a little more in-depth:\nclass List \u0026lt; Rbcli::Command # Declare a new command by subclassing Rbcli::Command description \u0026#39;TODO: Description goes here\u0026#39; # (Required) Short description for the global help usage \u0026lt;\u0026lt;-EOF TODO: Usage text goes here EOF # (Required) Long description for the command-specific help parameter :force, \u0026#39;Force testing\u0026#39;, type: :boolean, default: false, required: false # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times config_default :myopt2, description: \u0026#39;My Option #2\u0026#39;, default: \u0026#39;Default Value Here\u0026#39; # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config. # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options action do |params, args, global_opts, config| # (Required) Block to execute if the command is called. Rbcli::log.info { \u0026#39;These logs can go to STDERR, STDOUT, or a file\u0026#39; } # Example log. Interface is identical to Ruby\u0026#39;s logger puts \u0026#34;\\nArgs:\\n#{args}\u0026#34; # Arguments that came after the command on the CLI (i.e.: `mytool test bar baz` will yield args=[\u0026#39;bar\u0026#39;, \u0026#39;baz\u0026#39;]) puts \u0026#34;Params:\\n#{params}\u0026#34; # Parameters, as described through the option statements above puts \u0026#34;Global opts:\\n#{global_opts}\u0026#34; # Global Parameters, as descirbed in the Configurate section puts \u0026#34;Config:\\n#{config}\u0026#34; # Config file values puts \u0026#34;LocalState:\\n#{Rbcli.local_state}\u0026#34; # Local persistent state storage (when available) -- if unsure use Rbcli.local_state.nil? puts \u0026#34;RemoteState:\\n#{Rbcli.remote_state}\u0026#34; # Remote persistent state storage (when available) -- if unsure use Rbcli.remote_state.nil? puts \u0026#34;\\nDone!!!\u0026#34; end end Commands are declared to RBCli simply by subclassing them from Rbcli::Command as shown above. Then, you have a list of declarations that tell RBCli information about it. They are:\ndescription A short description of the command, which will appear in the top-level help (when the user runs mytool -h). usage A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you\u0026rsquo;d like. It will show up as a long, multi-line description when the user runs the command-sepcific help (mytool list -h). parameter Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on Options, Parameters, and Arguments config_default This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on User Config Files action This loads the block of code that will run when the command is called. It brings in all of the CLI and user config data as variables. We will also get into these in the next section Options, Parameters, and Arguments There is an additional declaration not shown here, extern. You can find more information on it in the section on Advanced Command Types\nCreating the \u0026ldquo;list\u0026rdquo; Command Now we\u0026rsquo;re going to modify this command to list the contents of the current directory to the terminal. So let\u0026rsquo;s change the code in that file to:\nclass List \u0026lt; Rbcli::Command description %q{List files in current directory} usage \u0026lt;\u0026lt;-EOF Ever wanted to see your files? Now you can! EOF action do |params, args, global_opts, config| filelist = [] # We store a list of the files in an array, including dotfiles if specified Dir.glob \u0026#34;./*\u0026#34; do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] outname += \u0026#39;/\u0026#39; if File.directory? filename filelist.append outname end # Apply color filelist.map! do |filename| if File.directory? filename filename.light_blue elsif File.executable? filename filename.light_green else filename end end if global_opts[:color] puts filelist end end Go ahead and test it out! The output doesn\u0026rsquo;t show much obviously, just a list of names and nothing else. Don\u0026rsquo;t worry though, we\u0026rsquo;ll fix that in the next secion.\nNext Steps Next we\u0026rsquo;re going to take a look at options, parameters, and arguments, and we\u0026rsquo;ll clean up our list command by using them. If you\u0026rsquo;d like to learn more about the additional command types in RBCli before continuing, see the Advanced Command Types documentation.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/whoami/",
 	"title": "My Letter To You",
 	"tags": [],
 	"description": "",
-	"content": "My Fellow Coder,\nI\u0026rsquo;m glad to see you are interested in RBCli. I\u0026rsquo;d like to introduce myself. My name is Andrew, and I\u0026rsquo;ve been a technologist since 1992 when my father bought our first family computer \u0026ndash; a 486DX2 which ran at 66Mhz (33Mhz if you turned off the \u0026lsquo;turbo\u0026rsquo; button) and came with MS DOS 5.0, QBasic, and a game already coded in it called Nibbles (if you care to see the code, die 5 times and don\u0026rsquo;t play again). I didn\u0026rsquo;t like that the game forced my name to be \u0026ldquo;Sammy\u0026rdquo;, and thought, \u0026ldquo;hey, if I can see the code, can\u0026rsquo;t I change it?\u0026rdquo;. So I did what any annoyed child would do and learned to code so I could do just that. I\u0026rsquo;d tell you what I changed it to, but I was so proud of myself for this simple feat that I changed it every 30 seconds and couldn\u0026rsquo;t settle on just one name. Then I performed my first ever hack, and figured out how to go through walls without dying. All of a sudden the world seemed limitless.\nI was only a child at the time, but on that day I learned that every \u0026ldquo;rule\u0026rdquo; in computing was an artifical construct and could be changed to suit your needs. Thus began my career in tech and my obsession to change the world with it. This is why RBCli was born.\nRBCli started as a collection of code that I would copy-paste between projects, until one day when I wondered if I could just find a framework that suited me. I couldn\u0026rsquo;t - in case you hadn\u0026rsquo;t guessed - so I decided to build my own and give it to the world. I would not have accomplished even half of what I have without the open source community, and this is to be the first of hopefully many contributions back.\nThe features in RBCli have been chosen from over 25 years of experience writing applications, building features that 3rd parties left out, managing large scale infrastructure, designing embedded systems, integrating enterprise systems, automating CI/CD, scripting my own computers, and so much more. I hope that you can find as much use out of it as I have.\nIf you\u0026rsquo;d like to get in touch with me at any time, feel free to email me at akhoury@live.com.\nAll the best,\nAndrew\nP.S.: If you really liked RBCli and want to support it, any amount you can help out with goes a long way.\n"
+	"content": "My Fellow Coder,\nI\u0026rsquo;m glad to see you are interested in RBCli. I\u0026rsquo;d like to introduce myself. My name is Andrew, and I\u0026rsquo;ve been a technologist since 1992 when my father bought our first family computer \u0026ndash; a 486DX2 which ran at 66Mhz (33Mhz if you turned off the \u0026rsquo;turbo\u0026rsquo; button) and came with MS DOS 5.0, QBasic, and a game already coded in it called Nibbles (if you care to see the code, die 5 times and don\u0026rsquo;t play again). I didn\u0026rsquo;t like that the game forced my name to be \u0026ldquo;Sammy\u0026rdquo;, and thought, \u0026ldquo;hey, if I can see the code, can\u0026rsquo;t I change it?\u0026rdquo;. So I did what any annoyed child would do and learned to code so I could do just that. I\u0026rsquo;d tell you what I changed it to, but I was so proud of myself for this simple feat that I changed it every 30 seconds and couldn\u0026rsquo;t settle on just one name. Then I performed my first ever hack, and figured out how to go through walls without dying. All of a sudden the world seemed limitless.\nI was only a child at the time, but on that day I learned that every \u0026ldquo;rule\u0026rdquo; in computing was an artifical construct and could be changed to suit your needs. Thus began my career in tech and my obsession to change the world with it. This is why RBCli was born.\nRBCli started as a collection of code that I would copy-paste between projects, until one day when I wondered if I could just find a framework that suited me. I couldn\u0026rsquo;t - in case you hadn\u0026rsquo;t guessed - so I decided to build my own and give it to the world. I would not have accomplished even half of what I have without the open source community, and this is to be the first of hopefully many contributions back.\nThe features in RBCli have been chosen from over 25 years of experience writing applications, building features that 3rd parties left out, managing large scale infrastructure, designing embedded systems, integrating enterprise systems, automating CI/CD, scripting my own computers, and so much more. I hope that you can find as much use out of it as I have.\nIf you\u0026rsquo;d like to get in touch with me at any time, feel free to email me at akhoury@live.com.\nAll the best,\nAndrew\nP.S.: If you really liked RBCli and want to support it, any amount you can help out with goes a long way.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/tutorial/40-options_parameters_and_arguments/",
 	"title": "Options, Parameters, and Arguments",
 	"tags": [],
 	"description": "",
-	"content": "If you\u0026rsquo;re already an experienced coder, you can jump to the last section of this document, the Simplified Reference (TLDR)\nCommand Line Structure In the previous section, you saw two parts of the RBCli command line structure - the executable followed by the command. However, RBCli is capable of more complex interaction. The structure is as follows:\ntoolname [options] command [parameters] argument1 argument2...  Options are command line parameters such as -f, or --force. These are available globally to every command. You can create your own, though several are already built-in and reserved for RBCli:  --config-file=\u0026lt;filename\u0026gt; allows specifying a config file location manually. --generate-config generates a config file for the user by writing out the defaults to a YAML file. This option will only appear if a config file has been set. The location is configurable, with more on that in the documentation on User Config Files). -v / --version shows the version. -h / --help shows the help.   Command represents the subcommands that you will create, such as list, test, or apply. Parameters are the same as options, but only apply to the specific subcommand being executed. In this case only the -h / --help parameter is provided automatically. Arguments are strings that don\u0026rsquo;t begin with a \u0026lsquo;-\u0026rsquo;, and are passed to the command\u0026rsquo;s code as an array. These can be used as subcommands or additional parameters for your command.  So a valid command could look something like these:\nmytool -n load --filename=foo.txt mytool parse foo.txt mytool show -l Note that all options and parameters will have both a short and long version of the parameter available for use.\nSo let\u0026rsquo;s take a look at how we define them.\nOptions You can find the options declarations under application/options.rb. You\u0026rsquo;ll see the example in the code:\noption :name, \u0026#39;Give me your name\u0026#39;, short: \u0026#39;n\u0026#39;, type: :string, default: \u0026#39;Jack\u0026#39;, required: false, permitted: [\u0026#39;Jack\u0026#39;, \u0026#39;Jill\u0026#39;] This won\u0026rsquo;t do for our tool, so let\u0026rsquo;s change it. Remember that these options will be applicable to all of our commands, so lets make it something appropriate:\noption :color, \u0026#39;Enable color output\u0026#39;, short: \u0026#39;c\u0026#39;, type: :boolean, default: false So now, let\u0026rsquo;s take advantage of this flag in our list command. Let\u0026rsquo;s change our block to:\naction do |params, args, global_opts, config| Dir.glob \u0026#34;./*\u0026#34; do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] outname += \u0026#39;/\u0026#39; if File.directory? filename # We change the color based on the kind of file shown if global_opts[:color] if File.directory? filename outname = outname.light_blue elsif File.executable? filename outname = outname.light_green end end puts outname end end Notice how we referenced the value by using global_opts[:color]. It\u0026rsquo;s that simple. To see it in action, run:\nmytool -c list Parameters Parameters work the same way as options, but they are localized to only the selected command. They are declared - as you probably guessed by now - in the command\u0026rsquo;s class. So let\u0026rsquo;s add the following lines to our list command within the class declaration:\nparameter :sort, \u0026#39;Sort output alphabetically\u0026#39;, type: :boolean, default: false parameter :all, \u0026#39;Show hidden files\u0026#39;, type: :boolean, default: false parameter :directoriesfirst, \u0026#39;Show directories on top\u0026#39;, type: :boolean, default: false And let\u0026rsquo;s modify our action block to utilize them:\naction do |params, args, global_opts, config| filelist = [] # We include dotfiles if specified include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0 # We store a list of the files in an array, including dotfiles if specified Dir.glob \u0026#34;./*\u0026#34;, include_dotfiles do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] outname += \u0026#39;/\u0026#39; if File.directory? filename filelist.append outname end # Sort alphabetically if specified filelist.sort! if params[:sort] # Put directories first if specified if params[:directoriesfirst] files = []; dirs = [] filelist.each do |filename| if File.directory? filename dirs.append(filename) else files.append(filename) end end filelist = dirs + files end # Apply color. We do this at the end now because color codes can alter the sorting. filelist.map! do |filename| if File.directory? filename filename.light_blue elsif File.executable? filename filename.light_green else filename end end if global_opts[:color] puts filelist end You should be able to run it now:\nmytool -c list -asd Note how the parameters come after the list command in the syntax above. As you create more commands, each will have its own unique set of parameters, while the options remain before the command and are available to all of them.\nUser Prompting There is an additional option when declaring parameters to prompt the user for a value if not entered on the command line. This can be done with the prompt: keyword. Let\u0026rsquo;s change one of our parameters to utilize it:\nparameter :sort, \u0026#39;Sort output alphabetically\u0026#39;, type: :boolean, default: false, prompt: \u0026#34;Sort output alphabetically?\u0026#34; Now, let\u0026rsquo;s run the tool while omitting the --sort parameter, as such:\nmytool -c list -ad This should give you the prompt:\nSort output alphabetically? (y/N): Because we set the parameter to default to false the default here is N, which is used if the user hits enter without entering a letter. If the default was set to true, then the Y would be capitalized and be the default.\nFor more information, see the documentation on Interactive Commands.\nArguments Lastly on the command line, there are arguments. Arguments are simply strings without the - character in front, and automatically get passed into an array in your applicaiton. Let\u0026rsquo;s take a look at how we can use them.\nUnlike options and parameters, arguments require no setup. So let\u0026rsquo;s assume that we want any arguments passed to the list command to be filenames that you want to display, and that you can pass multiple ones. Since arguments aren\u0026rsquo;t listed automatically by the help function, this is a good example of what to put in your usage text. Let\u0026rsquo;s take a look at what our class looks like now:\nclass List \u0026lt; Rbcli::Command description %q{List files in current directory} usage \u0026lt;\u0026lt;-EOF To list only specific files, you can enter filenames as arguments mytool list filename1 filename2... EOF parameter :sort, \u0026#39;Sort output alphabetically\u0026#39;, type: :boolean, default: false parameter :all, \u0026#39;Show hidden files\u0026#39;, type: :boolean, default: false parameter :directoriesfirst, \u0026#39;Show directories on top\u0026#39;, type: :boolean, default: false action do |params, args, global_opts, config| filelist = [] # We include dotfiles if specified include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0 # We store a list of the files in an array, including dotfiles if specified Dir.glob \u0026#34;./*\u0026#34;, include_dotfiles do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] next unless args.include? outname if args.length \u0026gt; 0 outname += \u0026#39;/\u0026#39; if File.directory? filename filelist.append outname end # Sort alphabetically if specified filelist.sort! if params[:sort] # Put directories first if specified if params[:directoriesfirst] files = []; dirs = [] filelist.each do |filename| if File.directory? filename dirs.append(filename) else files.append(filename) end end filelist = dirs + files end # Apply color. We do this at the end because color codes can alter the sorting filelist.map! do |filename| if File.directory? filename filename.light_blue elsif File.executable? filename filename.light_green else filename end end if global_opts[:color] puts filelist end end Simplified Reference (TLDR) RBCli enforces a CLI structure of:\ntoolname [options] command [parameters] argument1 argument2... Options are declared in application/options.rb file.\nParameters are declared in the respective command\u0026rsquo;s class declaration.\nArguments don\u0026rsquo;t need to be declared, and are passed in as an array to your commands. It is helpful to describe the argument purpose in the usage text declaration so that the user can see what to do in the help.\nOptions and parameters both use the same format:\noption :\u0026lt;name\u0026gt;, \u0026#34;\u0026lt;description_string\u0026gt;\u0026#34;, short: \u0026#39;\u0026lt;character\u0026gt;\u0026#39;, type: \u0026lt;variable_type\u0026gt;, default: \u0026lt;default_value\u0026gt;, permitted: [\u0026lt;array_of_permitted_values] parameter :\u0026lt;name\u0026gt;, \u0026#34;\u0026lt;description_string\u0026gt;\u0026#34;, short: \u0026#39;\u0026lt;character\u0026gt;\u0026#39;, type: \u0026lt;variable_type\u0026gt;, default: \u0026lt;default_value\u0026gt;, permitted: [\u0026lt;array_of_permitted_values]  name  (Required) The long name of the option, as a symbol. This will be represented as --name on the command line   description_string  (Required) A short description of the command that will appear in the help text for the user   type  (Required) The following types are supported: :string, :boolean or :flag, :integer, and :float   default  (Optional) A default value for the option if one isn\u0026rsquo;t entered (default: nil)   short  (Optional) A letter that acts as a shortcut for the option. This will allow users to apply the command as -n To not have a short value, set this to :none (default: the first letter of the long name)   required  (Optional) Specify whether the option is required from the user (default: false)   permitted  (Optional) An array of whitelisted values for the option (default: nil)    Next Steps Next, we\u0026rsquo;re going to take a quick look at how to publish and distribute your application, both publicly and within your organization.\n"
+	"content": "If you\u0026rsquo;re already an experienced coder, you can jump to the last section of this document, the Simplified Reference (TLDR)\nCommand Line Structure In the previous section, you saw two parts of the RBCli command line structure - the executable followed by the command. However, RBCli is capable of more complex interaction. The structure is as follows:\ntoolname [options] command [parameters] argument1 argument2... Options are command line parameters such as -f, or --force. These are available globally to every command. You can create your own, though several are already built-in and reserved for RBCli: --config-file=\u0026lt;filename\u0026gt; allows specifying a config file location manually. --generate-config generates a config file for the user by writing out the defaults to a YAML file. This option will only appear if a config file has been set. The location is configurable, with more on that in the documentation on User Config Files). -v / --version shows the version. -h / --help shows the help. Command represents the subcommands that you will create, such as list, test, or apply. Parameters are the same as options, but only apply to the specific subcommand being executed. In this case only the -h / --help parameter is provided automatically. Arguments are strings that don\u0026rsquo;t begin with a \u0026lsquo;-\u0026rsquo;, and are passed to the command\u0026rsquo;s code as an array. These can be used as subcommands or additional parameters for your command. So a valid command could look something like these:\nmytool -n load --filename=foo.txt mytool parse foo.txt mytool show -l Note that all options and parameters will have both a short and long version of the parameter available for use.\nSo let\u0026rsquo;s take a look at how we define them.\nOptions You can find the options declarations under application/options.rb. You\u0026rsquo;ll see the example in the code:\noption :name, \u0026#39;Give me your name\u0026#39;, short: \u0026#39;n\u0026#39;, type: :string, default: \u0026#39;Jack\u0026#39;, required: false, permitted: [\u0026#39;Jack\u0026#39;, \u0026#39;Jill\u0026#39;] This won\u0026rsquo;t do for our tool, so let\u0026rsquo;s change it. Remember that these options will be applicable to all of our commands, so lets make it something appropriate:\noption :color, \u0026#39;Enable color output\u0026#39;, short: \u0026#39;c\u0026#39;, type: :boolean, default: false So now, let\u0026rsquo;s take advantage of this flag in our list command. Let\u0026rsquo;s change our block to:\naction do |params, args, global_opts, config| Dir.glob \u0026#34;./*\u0026#34; do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] outname += \u0026#39;/\u0026#39; if File.directory? filename # We change the color based on the kind of file shown if global_opts[:color] if File.directory? filename outname = outname.light_blue elsif File.executable? filename outname = outname.light_green end end puts outname end end Notice how we referenced the value by using global_opts[:color]. It\u0026rsquo;s that simple. To see it in action, run:\nmytool -c list Parameters Parameters work the same way as options, but they are localized to only the selected command. They are declared - as you probably guessed by now - in the command\u0026rsquo;s class. So let\u0026rsquo;s add the following lines to our list command within the class declaration:\nparameter :sort, \u0026#39;Sort output alphabetically\u0026#39;, type: :boolean, default: false parameter :all, \u0026#39;Show hidden files\u0026#39;, type: :boolean, default: false parameter :directoriesfirst, \u0026#39;Show directories on top\u0026#39;, type: :boolean, default: false And let\u0026rsquo;s modify our action block to utilize them:\naction do |params, args, global_opts, config| filelist = [] # We include dotfiles if specified include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0 # We store a list of the files in an array, including dotfiles if specified Dir.glob \u0026#34;./*\u0026#34;, include_dotfiles do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] outname += \u0026#39;/\u0026#39; if File.directory? filename filelist.append outname end # Sort alphabetically if specified filelist.sort! if params[:sort] # Put directories first if specified if params[:directoriesfirst] files = []; dirs = [] filelist.each do |filename| if File.directory? filename dirs.append(filename) else files.append(filename) end end filelist = dirs + files end # Apply color. We do this at the end now because color codes can alter the sorting. filelist.map! do |filename| if File.directory? filename filename.light_blue elsif File.executable? filename filename.light_green else filename end end if global_opts[:color] puts filelist end You should be able to run it now:\nmytool -c list -asd Note how the parameters come after the list command in the syntax above. As you create more commands, each will have its own unique set of parameters, while the options remain before the command and are available to all of them.\nUser Prompting There is an additional option when declaring parameters to prompt the user for a value if not entered on the command line. This can be done with the prompt: keyword. Let\u0026rsquo;s change one of our parameters to utilize it:\nparameter :sort, \u0026#39;Sort output alphabetically\u0026#39;, type: :boolean, default: false, prompt: \u0026#34;Sort output alphabetically?\u0026#34; Now, let\u0026rsquo;s run the tool while omitting the --sort parameter, as such:\nmytool -c list -ad This should give you the prompt:\nSort output alphabetically? (y/N): Because we set the parameter to default to false the default here is N, which is used if the user hits enter without entering a letter. If the default was set to true, then the Y would be capitalized and be the default.\nFor more information, see the documentation on Interactive Commands.\nArguments Lastly on the command line, there are arguments. Arguments are simply strings without the - character in front, and automatically get passed into an array in your applicaiton. Let\u0026rsquo;s take a look at how we can use them.\nUnlike options and parameters, arguments require no setup. So let\u0026rsquo;s assume that we want any arguments passed to the list command to be filenames that you want to display, and that you can pass multiple ones. Since arguments aren\u0026rsquo;t listed automatically by the help function, this is a good example of what to put in your usage text. Let\u0026rsquo;s take a look at what our class looks like now:\nclass List \u0026lt; Rbcli::Command description %q{List files in current directory} usage \u0026lt;\u0026lt;-EOF To list only specific files, you can enter filenames as arguments mytool list filename1 filename2... EOF parameter :sort, \u0026#39;Sort output alphabetically\u0026#39;, type: :boolean, default: false parameter :all, \u0026#39;Show hidden files\u0026#39;, type: :boolean, default: false parameter :directoriesfirst, \u0026#39;Show directories on top\u0026#39;, type: :boolean, default: false action do |params, args, global_opts, config| filelist = [] # We include dotfiles if specified include_dotfiles = (params[:all]) ? File::FNM_DOTMATCH : 0 # We store a list of the files in an array, including dotfiles if specified Dir.glob \u0026#34;./*\u0026#34;, include_dotfiles do |filename| outname = filename.split(\u0026#39;/\u0026#39;)[1] next unless args.include? outname if args.length \u0026gt; 0 outname += \u0026#39;/\u0026#39; if File.directory? filename filelist.append outname end # Sort alphabetically if specified filelist.sort! if params[:sort] # Put directories first if specified if params[:directoriesfirst] files = []; dirs = [] filelist.each do |filename| if File.directory? filename dirs.append(filename) else files.append(filename) end end filelist = dirs + files end # Apply color. We do this at the end because color codes can alter the sorting filelist.map! do |filename| if File.directory? filename filename.light_blue elsif File.executable? filename filename.light_green else filename end end if global_opts[:color] puts filelist end end Simplified Reference (TLDR) RBCli enforces a CLI structure of:\ntoolname [options] command [parameters] argument1 argument2... Options are declared in application/options.rb file.\nParameters are declared in the respective command\u0026rsquo;s class declaration.\nArguments don\u0026rsquo;t need to be declared, and are passed in as an array to your commands. It is helpful to describe the argument purpose in the usage text declaration so that the user can see what to do in the help.\nOptions and parameters both use the same format:\noption :\u0026lt;name\u0026gt;, \u0026#34;\u0026lt;description_string\u0026gt;\u0026#34;, short: \u0026#39;\u0026lt;character\u0026gt;\u0026#39;, type: \u0026lt;variable_type\u0026gt;, default: \u0026lt;default_value\u0026gt;, permitted: [\u0026lt;array_of_permitted_values] parameter :\u0026lt;name\u0026gt;, \u0026#34;\u0026lt;description_string\u0026gt;\u0026#34;, short: \u0026#39;\u0026lt;character\u0026gt;\u0026#39;, type: \u0026lt;variable_type\u0026gt;, default: \u0026lt;default_value\u0026gt;, permitted: [\u0026lt;array_of_permitted_values] name (Required) The long name of the option, as a symbol. This will be represented as --name on the command line description_string (Required) A short description of the command that will appear in the help text for the user type (Required) The following types are supported: :string, :boolean or :flag, :integer, and :float default (Optional) A default value for the option if one isn\u0026rsquo;t entered (default: nil) short (Optional) A letter that acts as a shortcut for the option. This will allow users to apply the command as -n To not have a short value, set this to :none (default: the first letter of the long name) required (Optional) Specify whether the option is required from the user (default: false) permitted (Optional) An array of whitelisted values for the option (default: nil) Next Steps Next, we\u0026rsquo;re going to take a quick look at how to publish and distribute your application, both publicly and within your organization.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/tutorial/50-publishing/",
 	"title": "Publishing Your Application",
 	"tags": [],
 	"description": "",
-	"content": "RBCli creates projects designed to be easily distributed via either source control or as a gem. We\u0026rsquo;ll go over both methods.\nCommon Tasks Regardless of where you are publishing, certain tasks need to be accomplished. Namely, preparing the gemspec and the README.\nIn both files the items that need changing are pretty obvious \u0026ndash; you\u0026rsquo;ll need to fill out your name, email, etc, and replace the placeholder text in the README with something useful to your users.\nThen, for every release, you\u0026rsquo;ll need to update the version number in config/version.rb. This number is automatically used by the gemspec when versioning the gem in the system, and by RBCli when displaying help to the user and checking for automatic updates if you enable that feature (see Automatic Updates for more information).\nSource Control Distribution With Source Control distribution your users will be cloning the source code directly from your repository, and building and installing the gem locally. Thankfully, the process is pretty simple:\ngit clone \u0026lt;your_repo_here\u0026gt; gem build mytool.gemspec gem install mytool-*.gem Note that he README\u0026rsquo;s placeholder text has these commands already listed for your users, which you can leave as instructions.\nWhen using this method, we highly recommend using a git flow where you only merge to master when you are ready to release, this way your users don\u0026rsquo;t inadvertently download a buggy commit.\nRubygems.org Distribution If you\u0026rsquo;re distributing as a gem via Rubygems.org, you\u0026rsquo;ll need to follow a specific release process.\n Update the version number in config/version.rb Commit the change locally Run bundle exec rake release  This will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.\nRecommended Platforms As far as RBCli is concerned, all Git hosts and gem platforms work equally well, and as long as the code reaches your users in one piece it\u0026rsquo;s all the same. That said, if you\u0026rsquo;d like to take advantage of automatic update notifications for your users, please see the documentation for Automatic Updates for a list of supported platforms for that feature.\nNext Steps Congratulations! You\u0026rsquo;ve completed the tutorial on RBCli and should be able to make all sorts of CLI applications and tools with what you learned. That said, there are still many features in RBCli that we didn\u0026rsquo;t explore, which you can find in the Advanced section of this site. If you aren\u0026rsquo;t sure where to start, we recommend looking at User Config Files and going from there.\n"
+	"content": "RBCli creates projects designed to be easily distributed via either source control or as a gem. We\u0026rsquo;ll go over both methods.\nCommon Tasks Regardless of where you are publishing, certain tasks need to be accomplished. Namely, preparing the gemspec and the README.\nIn both files the items that need changing are pretty obvious \u0026ndash; you\u0026rsquo;ll need to fill out your name, email, etc, and replace the placeholder text in the README with something useful to your users.\nThen, for every release, you\u0026rsquo;ll need to update the version number in config/version.rb. This number is automatically used by the gemspec when versioning the gem in the system, and by RBCli when displaying help to the user and checking for automatic updates if you enable that feature (see Automatic Updates for more information).\nSource Control Distribution With Source Control distribution your users will be cloning the source code directly from your repository, and building and installing the gem locally. Thankfully, the process is pretty simple:\ngit clone \u0026lt;your_repo_here\u0026gt; gem build mytool.gemspec gem install mytool-*.gem Note that he README\u0026rsquo;s placeholder text has these commands already listed for your users, which you can leave as instructions.\nWhen using this method, we highly recommend using a git flow where you only merge to master when you are ready to release, this way your users don\u0026rsquo;t inadvertently download a buggy commit.\nRubygems.org Distribution If you\u0026rsquo;re distributing as a gem via Rubygems.org, you\u0026rsquo;ll need to follow a specific release process.\nUpdate the version number in config/version.rb Commit the change locally Run bundle exec rake release This will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.\nRecommended Platforms As far as RBCli is concerned, all Git hosts and gem platforms work equally well, and as long as the code reaches your users in one piece it\u0026rsquo;s all the same. That said, if you\u0026rsquo;d like to take advantage of automatic update notifications for your users, please see the documentation for Automatic Updates for a list of supported platforms for that feature.\nNext Steps Congratulations! You\u0026rsquo;ve completed the tutorial on RBCli and should be able to make all sorts of CLI applications and tools with what you learned. That said, there are still many features in RBCli that we didn\u0026rsquo;t explore, which you can find in the Advanced section of this site. If you aren\u0026rsquo;t sure where to start, we recommend looking at User Config Files and going from there.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/development/changelog/",
 	"title": "Changelog",
 	"tags": [],
 	"description": "",
-	"content": "0.3.1 (October 19, 2021) Bugfixes  Fixed prompt for option value to ignore nil defaults instead of displaying an empty string Skeleton script command script.sh updated to function correctly when development mode is enabled Updated Github Pages links to point to github.io instead of github.com which are being deprecated Updated dependencies, closing the security hole of the gem addressable \u0026lt;= 1.7.0  0.3 (July 31, 2020) Improvements  Deprecated Ruby code has been updated to be compatible with Ruby 2.7.x All depedencies have been updated to their latest versions and tested to ensure continued compatibility Old-style execution hooks have been fully deprecated in favor of declaring them in the Rbcli::Configurate.hooks block. To ensure compatibility, save your current hooks and generate new ones using the command rbcli hook Skeleton gemspec now includes spec.required_ruby_version, which matches Rbcli\u0026rsquo;s requirement Documentation updated to support latest Hugo and theme versions (Hugo 0.74.3 and hugo-theme-learn 2.5.0)  Features  Rbcli Deprecation Warnings now show the offending line of code to ease updating The $libdir global variable is defined by default in the skeleton project, allwoing easy access to the project\u0026rsquo;s lib folder  0.2.12 (July 29, 2019) Improvements  The base project skeleton now includes an improved structure for the lib/ folder Documentation now uses Hugo instead of MkDocs for site generation. Updated dependencies in project skeleton to latest versions  Features  Development mode can be enabled by setting the environment variables: RBCLI_ENV=development and RBCLI_DEVPATH=[path to local Rbcli folder] to simplify changes to Rbcli during development. Combined with setting alias rbcli='/path/to/rbcli/exe/rbcli', gem installation is not required for development work  0.2.11 (Feb 27, 2019) Improvements  Updated the dependent gem verions to use the latest available versions  Bugfixes  Fixed the nested triggers of the message I/O system  0.2.8 (Nov 7, 2018) Features  Added a standardized message I/O system  Improvements  Enabled the safe usage of anchors in YAML config files Improved the method of determining the script name to be more portable across OS\u0026rsquo;es  Bugfixes  Fixed an error which caused RBCli to crash when using local_state Fixed a bug which caused the rbcli init command to occassionally fail for mini and micro projects  Changes  Changed the rbcli init helptext to match the order of complexity of projects (standard -\u0026gt; mini -\u0026gt; micro)  0.2.7 (Oct 17, 2018) Improvements  Added a dev mode for scripts that allows using a local RBCli copy instead of requiring the gem to be installed  Bugfixes  Fixed a bug that caused the rbcli tool not to detect project folders correctly. Command parameter prompt: now works when required is set to true.  Changes  The rbcli init command now initializes into the current working directory instead of creating a new one. Fixed erroneous documentation about the \u0026lsquo;merge\u0026rsquo; setting on userspace config.  0.2.5 (Oct 8, 2018) Improvements  Added a useful error message when local or remote state is used but not initialized.  Bugfixes  Fixed a bug in the Github Updater where RBCli crashed when a version tag was not present in the repo. Fixed a bug where deleting a state key would crash Rbcli Fixed a bug where remote state crashed with certain configurations  0.2.4 (Sep 4, 2018)  This is a dummy release required to update the License in the Gemspec file. The license has not changed (GPLv3).  0.2.3 (Sep 4, 2018) Features  Interactive Commands \u0026ndash; Prompt the user for parameters with a given value  Improvements  Added documentation on logging  0.2.2 (Aug 22, 2018) Features Bugfixes  Fixed a bug that caused the logger\u0026rsquo;s target and level not to be configured properly via the Configurate block.  Improvements  Lazy-loading has been implemented in optional modules such as autoupdates, remote storage, etc. This means that if you do not enable them in the code, they will not be loaded into memory. This significantly improves loding times for applications. Abstraction system created for configuration. This has significantly simplified the existing codebase and makes future development easier. Deprecation warning system added. This allows for RBCli contributors to notify users of breaking changes that may impact their code. Folder structure has been simplified to ease development. Much of the code has been refactored.  Deprecations/Changes  The Rbcli module is now RBCli to better match the branding. The original Rbcli module will still work for this current release, with a warning, but future releases will require code changes. Hooks are now defined under the RBCli.Configurate.hooks block instead of RBCli.Configurate.me. The logger is now silent by default. To enable it, it must be configured either via the Configurate block or via the user\u0026rsquo;s config file.  0.2.1 (Aug 8, 2018) Features  Remote Execution added for Script and External commands  Bugfixes  Fixed a bug that caused RBCli to crash if a direct path mode script\u0026rsquo;s environment variables were declared as symbols  0.2.0 (Aug 5, 2018) Features  CLI tool Autoupdate Enabled; when an upgrade to RBCli is detected, the RBCli CLI tool will notify the developer. Official documentation created and hosted with Github Pages RBCli released under GPLv3 Copyright/License notice displayed via RBCli tool with rbcli license in accordance with GPLv3 guidelines  Bugfixes  Fixed version number loading for projects Cleaned up command usage help output Fixed script and external command generation  Improvements  A quick reference guide can now be found in README.md Autoupdate feature now allows supplying a custom message Direct Path Mode for External Commands now Added support for a lib folder in projects, as a place for custom code, which is automatically added to $LOAD_PATH for developers Improved language regarding external commands: Documentation now differentiates between Standard, Scripted, and External Commands Improved language regarding user config files: Now called Userspace Config Options and Parameters now allow specifying the letter to be used for the short version, or to disable it altogether Userspace config can now be disabled by setting the path to nil or removing the declaration  Deprecations/Changes  Removed deprecated and broken examples from the examples folder  "
+	"content": "0.3.3 (April 24, 2024) Improvements Tested with Ruby 3.3.0 Updated dependencies for Ruby 3.3.0 Updated dependnecies for Sekeleton projects Added a bundler/inline gemfile on mini and micro skeleton projects to simplify their use Replaced deprecated Trollop gem with its replacement, ManageIQ/Optimist Bugfixes Updated deprecated ERB call for skeleton generation to use new format 0.3.2 (October 28, 2023) Bugfixes Replaced several calls to the deprecated .exists? method with .exist? for compatibility with Ruby 3.2.0 Updated dependencies to latest versions Standardized on version locking to the latest Major version of dependencies rather than the latest Minor ones 0.3.1 (October 19, 2021) Bugfixes Fixed prompt for option value to ignore nil defaults instead of displaying an empty string Skeleton script command script.sh updated to function correctly when development mode is enabled Updated Github Pages links to point to github.io instead of github.com which are being deprecated Updated dependencies, closing the security hole of the gem addressable \u0026lt;= 1.7.0 0.3 (July 31, 2020) Improvements Deprecated Ruby code has been updated to be compatible with Ruby 2.7.x All depedencies have been updated to their latest versions and tested to ensure continued compatibility Old-style execution hooks have been fully deprecated in favor of declaring them in the Rbcli::Configurate.hooks block. To ensure compatibility, save your current hooks and generate new ones using the command rbcli hook Skeleton gemspec now includes spec.required_ruby_version, which matches Rbcli\u0026rsquo;s requirement Documentation updated to support latest Hugo and theme versions (Hugo 0.74.3 and hugo-theme-learn 2.5.0) Features Rbcli Deprecation Warnings now show the offending line of code to ease updating The $libdir global variable is defined by default in the skeleton project, allwoing easy access to the project\u0026rsquo;s lib folder 0.2.12 (July 29, 2019) Improvements The base project skeleton now includes an improved structure for the lib/ folder Documentation now uses Hugo instead of MkDocs for site generation. Updated dependencies in project skeleton to latest versions Features Development mode can be enabled by setting the environment variables: RBCLI_ENV=development and RBCLI_DEVPATH=[path to local Rbcli folder] to simplify changes to Rbcli during development. Combined with setting alias rbcli='/path/to/rbcli/exe/rbcli', gem installation is not required for development work 0.2.11 (Feb 27, 2019) Improvements Updated the dependent gem verions to use the latest available versions Bugfixes Fixed the nested triggers of the message I/O system 0.2.8 (Nov 7, 2018) Features Added a standardized message I/O system Improvements Enabled the safe usage of anchors in YAML config files Improved the method of determining the script name to be more portable across OS\u0026rsquo;es Bugfixes Fixed an error which caused RBCli to crash when using local_state Fixed a bug which caused the rbcli init command to occassionally fail for mini and micro projects Changes Changed the rbcli init helptext to match the order of complexity of projects (standard -\u0026gt; mini -\u0026gt; micro) 0.2.7 (Oct 17, 2018) Improvements Added a dev mode for scripts that allows using a local RBCli copy instead of requiring the gem to be installed Bugfixes Fixed a bug that caused the rbcli tool not to detect project folders correctly. Command parameter prompt: now works when required is set to true. Changes The rbcli init command now initializes into the current working directory instead of creating a new one. Fixed erroneous documentation about the \u0026lsquo;merge\u0026rsquo; setting on userspace config. 0.2.5 (Oct 8, 2018) Improvements Added a useful error message when local or remote state is used but not initialized. Bugfixes Fixed a bug in the Github Updater where RBCli crashed when a version tag was not present in the repo. Fixed a bug where deleting a state key would crash Rbcli Fixed a bug where remote state crashed with certain configurations 0.2.4 (Sep 4, 2018) This is a dummy release required to update the License in the Gemspec file. The license has not changed (GPLv3). 0.2.3 (Sep 4, 2018) Features Interactive Commands \u0026ndash; Prompt the user for parameters with a given value Improvements Added documentation on logging 0.2.2 (Aug 22, 2018) Features Bugfixes Fixed a bug that caused the logger\u0026rsquo;s target and level not to be configured properly via the Configurate block. Improvements Lazy-loading has been implemented in optional modules such as autoupdates, remote storage, etc. This means that if you do not enable them in the code, they will not be loaded into memory. This significantly improves loding times for applications. Abstraction system created for configuration. This has significantly simplified the existing codebase and makes future development easier. Deprecation warning system added. This allows for RBCli contributors to notify users of breaking changes that may impact their code. Folder structure has been simplified to ease development. Much of the code has been refactored. Deprecations/Changes The Rbcli module is now RBCli to better match the branding. The original Rbcli module will still work for this current release, with a warning, but future releases will require code changes. Hooks are now defined under the RBCli.Configurate.hooks block instead of RBCli.Configurate.me. The logger is now silent by default. To enable it, it must be configured either via the Configurate block or via the user\u0026rsquo;s config file. 0.2.1 (Aug 8, 2018) Features Remote Execution added for Script and External commands Bugfixes Fixed a bug that caused RBCli to crash if a direct path mode script\u0026rsquo;s environment variables were declared as symbols 0.2.0 (Aug 5, 2018) Features CLI tool Autoupdate Enabled; when an upgrade to RBCli is detected, the RBCli CLI tool will notify the developer. Official documentation created and hosted with Github Pages RBCli released under GPLv3 Copyright/License notice displayed via RBCli tool with rbcli license in accordance with GPLv3 guidelines Bugfixes Fixed version number loading for projects Cleaned up command usage help output Fixed script and external command generation Improvements A quick reference guide can now be found in README.md Autoupdate feature now allows supplying a custom message Direct Path Mode for External Commands now Added support for a lib folder in projects, as a place for custom code, which is automatically added to $LOAD_PATH for developers Improved language regarding external commands: Documentation now differentiates between Standard, Scripted, and External Commands Improved language regarding user config files: Now called Userspace Config Options and Parameters now allow specifying the letter to be used for the short version, or to disable it altogether Userspace config can now be disabled by setting the path to nil or removing the declaration Deprecations/Changes Removed deprecated and broken examples from the examples folder "
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/",
 	"title": "",
 	"tags": [],
 	"description": "",
-	"content": "This is RBCli As technologists today, we work with the command line a lot. We script a lot. We write tools to share with each other to make our lives easier. We even write applications to make up for missing features in the 3rd party software that we buy. Unfortunately, when writing CLI tools, this process has typically been very painful. We\u0026rsquo;ve been working with low-level frameworks for decades; frameworks like getopt (1980) and curses (1977). They fit their purpose well; they were both computationally lightweight for the computers of the day, and they gave engineers full control and flexibility when it came to how things were built. Over the years, we\u0026rsquo;ve used them to settle on several design patterns that we know work well. Patterns as to what a CLI command looks like, what a config file looks like, what remote execution looks like, and even how to use locks (mutexes, semaphores, etc) to control application flow and data atomicity. Yet we\u0026rsquo;re stuck writing the same low-level code anytime we want to write our tooling. Not anymore.\nEnter RBCli. RBCli is a framework to quickly develop advanced command-line tools in Ruby. It has been written from the ground up with the needs of the modern technologist in mind, designed to make advanced CLI tool development as painless as possible. In RBCli, low-level code has been wrapped and/or replaced with higher-level methods. Much of the functionality has even been reduced to single methods: for example, it takes just one declaration to define, load, and generate a user\u0026rsquo;s config file at the appropriate times. Many other features are automated and require no work by the engineer. These make RBCli a fundamental re-thining of how we develop CLI tools, enabling the rapid development of applications for everyone from hobbyists to enterprises.\nSome of its key features include:\n  Simple DSL Interface: To cut down on the amount of code that needs to be written, RBCli has a DSL that is designed to cut to the chase. This makes the work a lot less tedious.\n  Multiple Levels of Parameters and Arguments: Forget about writing parsers for command-line options, or about having to differentiate between parameters and arguments. All of that work is taken care of.\n  Config File Generation: Easily piece together a default configuration even with declarations in different parts of the code. Then the user can generate their own configuration, and it gets stored in whatever location you\u0026rsquo;d like.\n  Multiple Hooks and Entry Points: Define commands, pre-execution hooks, post-execution hooks, and first_run hooks to quickly and easily customize the flow of your application code.\n  Logging: Keep track of all instances of your tool through logging. Logs can go to STDOUT, STDERR, or a given file, making them compatible with log aggregators such as Splunk, Logstash, and many others.\n  Local State Storage: Easily manage a set of data that persists between runs. You get access to a hash that is automatically kept in-sync with a file on disk.\n  Remote State: It works just like Local State Storage, but store the data on a remote server! It can be used in tandem with Local State Storage or on its own. Currently supports AWS DyanmoDB.\n  State Locking and Sharing: Share remote state safely between users with built-in locking! When enabled, it makes sure that only one user is accessing the data at any given time.\n  Automatic Update Notifications: Just provide the gem name or git repo, and RBCli will take care of notifying users!\n  External Script Wrapping: High-level wrapping for Bash scripts, or any other applcication you\u0026rsquo;d like to wrap into a command.\n  Project Structure and Generators: Create a well-defined project directory structure which organizes your code and allows you to package and distribute your application as a Gem. Generators can also help speed up the process of creating new commands, scripts, and hooks!\n  Remote Execution: Automatically execute commands on remote machines via SSH\n  Interactive Commands: Automatically prompt users for paramter values if not given on the command line. This pattern allows for easy user interaction while still allowing scripting without the use of expect.\n  If you\u0026rsquo;re just getting started with RBCli, take a look at the Tutorial. Or take a look at the Advanced menu to look through RBCli\u0026rsquo;s additional featureset.\n"
+	"content": "This is RBCli As technologists today, we work with the command line a lot. We script a lot. We write tools to share with each other to make our lives easier. We even write applications to make up for missing features in the 3rd party software that we buy. Unfortunately, when writing CLI tools, this process has typically been very painful. We\u0026rsquo;ve been working with low-level frameworks for decades; frameworks like getopt (1980) and curses (1977). They fit their purpose well; they were both computationally lightweight for the computers of the day, and they gave engineers full control and flexibility when it came to how things were built. Over the years, we\u0026rsquo;ve used them to settle on several design patterns that we know work well. Patterns as to what a CLI command looks like, what a config file looks like, what remote execution looks like, and even how to use locks (mutexes, semaphores, etc) to control application flow and data atomicity. Yet we\u0026rsquo;re stuck writing the same low-level code anytime we want to write our tooling. Not anymore.\nEnter RBCli. RBCli is a framework to quickly develop advanced command-line tools in Ruby. It has been written from the ground up with the needs of the modern technologist in mind, designed to make advanced CLI tool development as painless as possible. In RBCli, low-level code has been wrapped and/or replaced with higher-level methods. Much of the functionality has even been reduced to single methods: for example, it takes just one declaration to define, load, and generate a user\u0026rsquo;s config file at the appropriate times. Many other features are automated and require no work by the engineer. These make RBCli a fundamental re-thining of how we develop CLI tools, enabling the rapid development of applications for everyone from hobbyists to enterprises.\nSome of its key features include:\nSimple DSL Interface: To cut down on the amount of code that needs to be written, RBCli has a DSL that is designed to cut to the chase. This makes the work a lot less tedious.\nMultiple Levels of Parameters and Arguments: Forget about writing parsers for command-line options, or about having to differentiate between parameters and arguments. All of that work is taken care of.\nConfig File Generation: Easily piece together a default configuration even with declarations in different parts of the code. Then the user can generate their own configuration, and it gets stored in whatever location you\u0026rsquo;d like.\nMultiple Hooks and Entry Points: Define commands, pre-execution hooks, post-execution hooks, and first_run hooks to quickly and easily customize the flow of your application code.\nLogging: Keep track of all instances of your tool through logging. Logs can go to STDOUT, STDERR, or a given file, making them compatible with log aggregators such as Splunk, Logstash, and many others.\nLocal State Storage: Easily manage a set of data that persists between runs. You get access to a hash that is automatically kept in-sync with a file on disk.\nRemote State: It works just like Local State Storage, but store the data on a remote server! It can be used in tandem with Local State Storage or on its own. Currently supports AWS DyanmoDB.\nState Locking and Sharing: Share remote state safely between users with built-in locking! When enabled, it makes sure that only one user is accessing the data at any given time.\nAutomatic Update Notifications: Just provide the gem name or git repo, and RBCli will take care of notifying users!\nExternal Script Wrapping: High-level wrapping for Bash scripts, or any other applcication you\u0026rsquo;d like to wrap into a command.\nProject Structure and Generators: Create a well-defined project directory structure which organizes your code and allows you to package and distribute your application as a Gem. Generators can also help speed up the process of creating new commands, scripts, and hooks!\nRemote Execution: Automatically execute commands on remote machines via SSH\nInteractive Commands: Automatically prompt users for paramter values if not given on the command line. This pattern allows for easy user interaction while still allowing scripting without the use of expect.\nIf you\u0026rsquo;re just getting started with RBCli, take a look at the Tutorial. Or take a look at the Advanced menu to look through RBCli\u0026rsquo;s additional featureset.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/advanced/automatic_updates/",
@@ -116,14 +116,14 @@
 	"title": "Command Types",
 	"tags": [],
 	"description": "",
-	"content": "RBCli has three different command types:\n Standard Commands (Ruby-based) Scripted Commands (Ruby+Bash based) External Commands (Wrapping a 3rd party application)  This document is provided to be a reference. If you would like an in-depth tutorial, please see Your First Command.\nGeneral Command Structure Commands in RBCli are created by subclassing Rbcli::Command. All commands share a certain common structure:\nclass List \u0026lt; Rbcli::Command # Declare a new command by subclassing Rbcli::Command description \u0026#39;TODO: Description goes here\u0026#39; # (Required) Short description for the global help usage \u0026lt;\u0026lt;-EOF TODO: Usage text goes here EOF # (Required) Long description for the command-specific help parameter :force, \u0026#39;Force testing\u0026#39;, type: :boolean, default: false, required: false # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times config_default :myopt2, description: \u0026#39;My Option #2\u0026#39;, default: \u0026#39;Default Value Here\u0026#39; # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config. # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options end  description  A short description of the command, which will appear in the top-level help (when the user runs mytool -h).   usage  A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you\u0026rsquo;d like. It will show up as a long, multi-line description when the user runs the command-sepcific help (mytool list -h).   parameter  Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on Options, Parameters, and Arguments   config_default  This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on User Config Files    Standard Commands Standard commands are written as ruby code. To create a standard command called list, run:\nrbcli command --name=list #or rbcli command -n list A standard command can be identified by the presence of an action block in the definition:\nclass List \u0026lt; Rbcli::Command action do |params, args, global_opts, config| # Code goes here end end Your application\u0026rsquo;s parameters, arguments, options, and config are available in the variables passed into the block. For more information on these, see Options, Parameters, and Arguments.\nScripted Commands Scripted commands are part Ruby, part Bash scripting. They are a good choice to use if you feel something might be easier or more performant to script with Bash, or if you already have a Bash script you\u0026rsquo;d like to use in your project. You can create one with:\nrbcli script -n list This will create two files in your RBCli project: a Ruby file with the common command declaration (see General Command Structure), and a bash script in the folder application/commands/scripts/.\nYou can tell a command is a script by the line:\nclass List \u0026lt; Rbcli::Command script end RBCli will pass along your applications config and CLI parameters through JSON environment variables. To make things easy, a Bash library is provided that makes retrieving and parsing these variables easy. It is already imported when you generate the command, with the line:\nsource $(echo $(cd \u0026#34;$(dirname $(gem which rbcli))/../lib-sh\u0026#34; \u0026amp;\u0026amp; pwd)/lib-rbcli.sh) This will find the library which is stored on the system as part of the RBCli gem.\nYou can then retrieve the values present in your variables like such:\nrbcli params rbcli args rbcli global_opts rbcli config rbcli myvars echo \u0026#34;Usage Examples:\u0026#34; echo \u0026#34;Log Level: $(rbcli config .logger.log_level)\u0026#34; echo \u0026#34;Log Target: $(rbcli config .logger.log_target)\u0026#34; echo \u0026#34;First Argument (if passed): $(rbcli args .[0])\u0026#34; For your convenience, the script will have all the instructions needed there. For more instructions on how to use JQ syntax to parse values, see the JQ documentation.\nExternal Commands External Commands are used to wrap 3rd party applications. RBCli accomplishes this by allowing you to set environment variables and command line parameters based on your input variables.\nRBCli provides this feature through the extern keyword. It provides two modes \u0026ndash; direct path and variable path \u0026ndash; which work similarly.\nDirect Path Mode Direct path mode is the simpler mode of the two External Command modes. It allows you to provide a specific command with environment variables set, though it does not allow using RBCli parameters, arguments, options, and config.\nclass List \u0026lt; Rbcli::Command extern path: \u0026#39;path/to/application\u0026#39;, envvars: {MYVAR: \u0026#39;some_value\u0026#39;} # (Required) Runs a given application, with optional environment variables, when the user runs the command. end Here, we supply a string to run the command. We can optioanlly provide environment variables which will be set for the external application.\nVariable Path Mode Variable Path mode works the same as Direct Path Mode, only instead of providing a string we provide a block that returns a string (which will be the command executed). This allows us to generate different commands based on the CLI parameters that the user passed, or pass configuration as CLI parameters to the external application:\nclass Test \u0026lt; Rbcli::Command extern envvars: {MY_OTHER_VAR: \u0026#39;another_value\u0026#39;} do |params, args, global_opts, config| # Alternate usage. Supplying a block instead of a path allows us to modify the command based on the arguments and configuration supplied by the user. This allows passing config settings as command line arguments to external applications. The block must return a string, which is the command to be executed. cmd = \u0026#39;/path/to/application\u0026#39; cmd += \u0026#39; --test-script foo --ignore-errors\u0026#39; if params[:force] cmd end end NOTE: Passing user-supplied data as part of the command string may be a security risk (example: /path/to/application --name #{params[:name]}). It is highly recommended to provide the fixed strings yourself, and only select which strings are used based on the variables provided. This is demonstrated in the example above.\n"
+	"content": "RBCli has three different command types:\nStandard Commands (Ruby-based) Scripted Commands (Ruby+Bash based) External Commands (Wrapping a 3rd party application) This document is provided to be a reference. If you would like an in-depth tutorial, please see Your First Command.\nGeneral Command Structure Commands in RBCli are created by subclassing Rbcli::Command. All commands share a certain common structure:\nclass List \u0026lt; Rbcli::Command # Declare a new command by subclassing Rbcli::Command description \u0026#39;TODO: Description goes here\u0026#39; # (Required) Short description for the global help usage \u0026lt;\u0026lt;-EOF TODO: Usage text goes here EOF # (Required) Long description for the command-specific help parameter :force, \u0026#39;Force testing\u0026#39;, type: :boolean, default: false, required: false # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times config_default :myopt2, description: \u0026#39;My Option #2\u0026#39;, default: \u0026#39;Default Value Here\u0026#39; # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config. # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options end description A short description of the command, which will appear in the top-level help (when the user runs mytool -h). usage A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you\u0026rsquo;d like. It will show up as a long, multi-line description when the user runs the command-sepcific help (mytool list -h). parameter Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on Options, Parameters, and Arguments config_default This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on User Config Files Standard Commands Standard commands are written as ruby code. To create a standard command called list, run:\nrbcli command --name=list #or rbcli command -n list A standard command can be identified by the presence of an action block in the definition:\nclass List \u0026lt; Rbcli::Command action do |params, args, global_opts, config| # Code goes here end end Your application\u0026rsquo;s parameters, arguments, options, and config are available in the variables passed into the block. For more information on these, see Options, Parameters, and Arguments.\nScripted Commands Scripted commands are part Ruby, part Bash scripting. They are a good choice to use if you feel something might be easier or more performant to script with Bash, or if you already have a Bash script you\u0026rsquo;d like to use in your project. You can create one with:\nrbcli script -n list This will create two files in your RBCli project: a Ruby file with the common command declaration (see General Command Structure), and a bash script in the folder application/commands/scripts/.\nYou can tell a command is a script by the line:\nclass List \u0026lt; Rbcli::Command script end RBCli will pass along your applications config and CLI parameters through JSON environment variables. To make things easy, a Bash library is provided that makes retrieving and parsing these variables easy. It is already imported when you generate the command, with the line:\nsource $(echo $(cd \u0026#34;$(dirname $(gem which rbcli))/../lib-sh\u0026#34; \u0026amp;\u0026amp; pwd)/lib-rbcli.sh) This will find the library which is stored on the system as part of the RBCli gem.\nYou can then retrieve the values present in your variables like such:\nrbcli params rbcli args rbcli global_opts rbcli config rbcli myvars echo \u0026#34;Usage Examples:\u0026#34; echo \u0026#34;Log Level: $(rbcli config .logger.log_level)\u0026#34; echo \u0026#34;Log Target: $(rbcli config .logger.log_target)\u0026#34; echo \u0026#34;First Argument (if passed): $(rbcli args .[0])\u0026#34; For your convenience, the script will have all the instructions needed there. For more instructions on how to use JQ syntax to parse values, see the JQ documentation.\nExternal Commands External Commands are used to wrap 3rd party applications. RBCli accomplishes this by allowing you to set environment variables and command line parameters based on your input variables.\nRBCli provides this feature through the extern keyword. It provides two modes \u0026ndash; direct path and variable path \u0026ndash; which work similarly.\nDirect Path Mode Direct path mode is the simpler mode of the two External Command modes. It allows you to provide a specific command with environment variables set, though it does not allow using RBCli parameters, arguments, options, and config.\nclass List \u0026lt; Rbcli::Command extern path: \u0026#39;path/to/application\u0026#39;, envvars: {MYVAR: \u0026#39;some_value\u0026#39;} # (Required) Runs a given application, with optional environment variables, when the user runs the command. end Here, we supply a string to run the command. We can optioanlly provide environment variables which will be set for the external application.\nVariable Path Mode Variable Path mode works the same as Direct Path Mode, only instead of providing a string we provide a block that returns a string (which will be the command executed). This allows us to generate different commands based on the CLI parameters that the user passed, or pass configuration as CLI parameters to the external application:\nclass Test \u0026lt; Rbcli::Command extern envvars: {MY_OTHER_VAR: \u0026#39;another_value\u0026#39;} do |params, args, global_opts, config| # Alternate usage. Supplying a block instead of a path allows us to modify the command based on the arguments and configuration supplied by the user. This allows passing config settings as command line arguments to external applications. The block must return a string, which is the command to be executed. cmd = \u0026#39;/path/to/application\u0026#39; cmd += \u0026#39; --test-script foo --ignore-errors\u0026#39; if params[:force] cmd end end NOTE: Passing user-supplied data as part of the command string may be a security risk (example: /path/to/application --name #{params[:name]}). It is highly recommended to provide the fixed strings yourself, and only select which strings are used based on the variables provided. This is demonstrated in the example above.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/advanced/distributed_state_locking/",
 	"title": "Distributed State and Locking",
 	"tags": [],
 	"description": "",
-	"content": "Distributed Locking allows a Remote State to be shared among multiple users of the application to make writes appear atomic between sessions. To use it, simply set the locking: parameter to true when enabling remote state.\nThis is how locking works:\n The application attempts to acquire a lock on the remote state when you first access it If the backend is locked by a different application, wait and try again If it succeeds, the lock is held and refreshed periodically When the application exits, the lock is released If the application does not refresh its lock, or fails to release it when it exits, the lock will automatically expire within 60 seconds If another application steals the lock (unlikely but possible), and the application tries to save data, a StandardError will be thrown You can manually attempt to lock/unlock by calling Rbcli.remote_state.lock or Rbcli.remote_state.unlock, respectively.  Manual Locking Remember: all state in Rbcli is lazy-loaded. Therefore, RBCli wll only attempt to lock the data when you first try to access it. If you need to make sure that the data is locked before executing a block of code, use:\nRbcli.remote_state.refresh to force the lock and retrieve the latest data. You can force an unlock by calling:\nRbcli.remote_state.disconnect Even if you do not want to store any data, you can leverage manual locking to control access to a different shared resource, such as a stateful API. For example, if you write a cloud deployment toolkit, you can ensure that only one user is attempting to modify a deployment at any given time.\n"
+	"content": "Distributed Locking allows a Remote State to be shared among multiple users of the application to make writes appear atomic between sessions. To use it, simply set the locking: parameter to true when enabling remote state.\nThis is how locking works:\nThe application attempts to acquire a lock on the remote state when you first access it If the backend is locked by a different application, wait and try again If it succeeds, the lock is held and refreshed periodically When the application exits, the lock is released If the application does not refresh its lock, or fails to release it when it exits, the lock will automatically expire within 60 seconds If another application steals the lock (unlikely but possible), and the application tries to save data, a StandardError will be thrown You can manually attempt to lock/unlock by calling Rbcli.remote_state.lock or Rbcli.remote_state.unlock, respectively. Manual Locking Remember: all state in Rbcli is lazy-loaded. Therefore, RBCli wll only attempt to lock the data when you first try to access it. If you need to make sure that the data is locked before executing a block of code, use:\nRbcli.remote_state.refresh to force the lock and retrieve the latest data. You can force an unlock by calling:\nRbcli.remote_state.disconnect Even if you do not want to store any data, you can leverage manual locking to control access to a different shared resource, such as a stateful API. For example, if you write a cloud deployment toolkit, you can ensure that only one user is attempting to modify a deployment at any given time.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/advanced/hooks/",
@@ -144,7 +144,7 @@
 	"title": "Logging",
 	"tags": [],
 	"description": "",
-	"content": "Logging with RBCli is straightforward - it looks at the config file for logging settings, and instantiates a single, globally accessible Logger object. You can access it within a standard command like this:\nRbcli::log.info { \u0026#39;These logs can go to STDERR, STDOUT, or a file\u0026#39; } Enabling Logging To enable logging, simply set the default values in the config/logging.rb file:\nlog_level :info log_target \u0026#39;stderr\u0026#39;  log_level  You can set the default log level using either numeric or standard Ruby logger levels: 0-5, or DEBUG \u0026lt; INFO \u0026lt; WARN \u0026lt; ERROR \u0026lt; FATAL \u0026lt; UNKNOWN   log_target  This specifies where the logs will be placed. Valid values are nil (disables logging), \u0026lsquo;STDOUT\u0026rsquo;, \u0026lsquo;STDERR\u0026rsquo;, or a file path (all as strings).    Userspace Config Overrides If Userspace Configuration is enabled, these options will also be present in the user\u0026rsquo;s config file to override defaults:\n# Log Settings logger: log_level: warn  # 0-5, or DEBUG \u0026lt; INFO \u0026lt; WARN \u0026lt; ERROR \u0026lt; FATAL \u0026lt; UNKNOWN log_target: stderr  # STDOUT, STDERR, or a file path "
+	"content": "Logging with RBCli is straightforward - it looks at the config file for logging settings, and instantiates a single, globally accessible Logger object. You can access it within a standard command like this:\nRbcli::log.info { \u0026#39;These logs can go to STDERR, STDOUT, or a file\u0026#39; } Enabling Logging To enable logging, simply set the default values in the config/logging.rb file:\nlog_level :info log_target \u0026#39;stderr\u0026#39; log_level You can set the default log level using either numeric or standard Ruby logger levels: 0-5, or DEBUG \u0026lt; INFO \u0026lt; WARN \u0026lt; ERROR \u0026lt; FATAL \u0026lt; UNKNOWN log_target This specifies where the logs will be placed. Valid values are nil (disables logging), \u0026lsquo;STDOUT\u0026rsquo;, \u0026lsquo;STDERR\u0026rsquo;, or a file path (all as strings). Userspace Config Overrides If Userspace Configuration is enabled, these options will also be present in the user\u0026rsquo;s config file to override defaults:\n# Log Settings logger: log_level: warn # 0-5, or DEBUG \u0026lt; INFO \u0026lt; WARN \u0026lt; ERROR \u0026lt; FATAL \u0026lt; UNKNOWN log_target: stderr # STDOUT, STDERR, or a file path "
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/advanced/remote_execution/",
@@ -158,14 +158,14 @@
 	"title": "State Storage",
 	"tags": [],
 	"description": "",
-	"content": "RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.\nLocal State RBCli\u0026rsquo;s local state storage gives you access to a hash that is automatically persisted to disk when changes are made.\nConfiguration You can configure it in config/storage.rb.\nlocal_state \u0026#39;/var/mytool/localstate\u0026#39;, force_creation: true, halt_on_error: true There are three parameters to configure it with:\n The path as a string (self-explanatory) force_creation  This will attempt to create the path and file if it does not exist (equivalent to an mkdir -p and touch in linux)   halt_on_error  RBCli\u0026rsquo;s default behavior is to raise an exception if the file can not be created, read, or updated at any point in time If this is set to false, RBCli will silence any errors pertaining to file access and will fall back to whatever data is available. Note that if this is enabled, changes made to the state may not be persisted to disk.  If creation fails and file does not exist, you start with an empty hash If file exists but can\u0026rsquo;t be read, you will have an empty hash If file can be read but not written, the hash will be populated with the data. Writes will be stored in memory while the application is running, but will not be persisted to disk.      Access and Usage Once configured you can access it with a standard hash syntax in your Standard Commands:\nRbcli.local_state[:yourkeyhere] The methods available for use at the top level are as follows:\nHash native methods:\n [] (Regular hash syntax. Keys are accessed via either symbols or strings indifferently.) []= (Assignment operator) delete each key?  Additional methods:\n commit  Every assignment to the top level of the hash will result in a write to disk (for example: Rbcli.local_state[:yourkey] = 'foo'). However, if you are manipulating nested hashes, these saves will not be triggered. You can trigger them manually by calling commit.   clear  Resets the data back to an empty hash.   refresh  Loads the most current version of the data from the disk   disconnect  Removes the data from memory and sets Rbcli.local_state = nil. Data will be read from disk again on next access.    Every assignment will result in a write to disk, so if an operation will require a large number of assignments/writes it should be performed to a different hash before beign assigned to this one.\nRemote State RBCli\u0026rsquo;s remote state storage gives you access to a hash that is automatically persisted to a remote storage location when changes are made. It has optional locking built-in, meaning that multiple users may share remote state without any data consistency issues.\nCurrently, this feature requires AWS DynamoDB, though other backend systems will be added in the future.\nConfiguration Before DynamoDB can be used, AWS API credentials have to be created and made available. RBCli will attempt to find credentials from the following locations in order:\n User\u0026rsquo;s config file Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY User\u0026rsquo;s AWSCLI configuration at ~/.aws/credentials  For more information about generating and storing AWS credentials, see Configuring the AWS SDK for Ruby. Please make sure that your users are aware that they will need to provide their own credentials to use this feature.\nYou can configure it in config/storage.rb.\nremote_state_dynamodb table_name: \u0026#39;mytable\u0026#39;, region: \u0026#39;us-east-1\u0026#39;, force_creation: true, halt_on_error: true, locking: false These are the parameters:\n table_name  The name of the DynamoDB table to use.   region  The AWS region that the database is located   force_creation  Creates the DynamoDB table if it does not already exist   halt_on_error  Similar to the way Local State works, setting this to false will silence any errors in connecting to the DynamoDB table. Instead, your application will simply have access to an empty hash that does not get persisted anywhere. This is good for use cases that involve using this storage as a cache, where a connection error might mean the feature doesn\u0026rsquo;t work but its not important enough to interrupt the user.   locking  Setting this to true enables locking, meaning only one instance of your application can access the shared data at any given time. For more information see Distributed State Locking.    Access and Usage Once configured you can access it with a standard hash syntax:\nRbcli.remote_state[:yourkeyhere] This works the same way that Local State does, with the same performance caveats (try not to write too frequently).\nNote that all state in Rbcli is lazy-loaded, so no connections will be made until your code attempts to access the data even if the feature is enabled.\nFor more information on the available commands, see the documentation on Local State\n"
+	"content": "RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.\nLocal State RBCli\u0026rsquo;s local state storage gives you access to a hash that is automatically persisted to disk when changes are made.\nConfiguration You can configure it in config/storage.rb.\nlocal_state \u0026#39;/var/mytool/localstate\u0026#39;, force_creation: true, halt_on_error: true There are three parameters to configure it with:\nThe path as a string (self-explanatory) force_creation This will attempt to create the path and file if it does not exist (equivalent to an mkdir -p and touch in linux) halt_on_error RBCli\u0026rsquo;s default behavior is to raise an exception if the file can not be created, read, or updated at any point in time If this is set to false, RBCli will silence any errors pertaining to file access and will fall back to whatever data is available. Note that if this is enabled, changes made to the state may not be persisted to disk. If creation fails and file does not exist, you start with an empty hash If file exists but can\u0026rsquo;t be read, you will have an empty hash If file can be read but not written, the hash will be populated with the data. Writes will be stored in memory while the application is running, but will not be persisted to disk. Access and Usage Once configured you can access it with a standard hash syntax in your Standard Commands:\nRbcli.local_state[:yourkeyhere] The methods available for use at the top level are as follows:\nHash native methods:\n[] (Regular hash syntax. Keys are accessed via either symbols or strings indifferently.) []= (Assignment operator) delete each key? Additional methods:\ncommit Every assignment to the top level of the hash will result in a write to disk (for example: Rbcli.local_state[:yourkey] = 'foo'). However, if you are manipulating nested hashes, these saves will not be triggered. You can trigger them manually by calling commit. clear Resets the data back to an empty hash. refresh Loads the most current version of the data from the disk disconnect Removes the data from memory and sets Rbcli.local_state = nil. Data will be read from disk again on next access. Every assignment will result in a write to disk, so if an operation will require a large number of assignments/writes it should be performed to a different hash before beign assigned to this one.\nRemote State RBCli\u0026rsquo;s remote state storage gives you access to a hash that is automatically persisted to a remote storage location when changes are made. It has optional locking built-in, meaning that multiple users may share remote state without any data consistency issues.\nCurrently, this feature requires AWS DynamoDB, though other backend systems will be added in the future.\nConfiguration Before DynamoDB can be used, AWS API credentials have to be created and made available. RBCli will attempt to find credentials from the following locations in order:\nUser\u0026rsquo;s config file Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY User\u0026rsquo;s AWSCLI configuration at ~/.aws/credentials For more information about generating and storing AWS credentials, see Configuring the AWS SDK for Ruby. Please make sure that your users are aware that they will need to provide their own credentials to use this feature.\nYou can configure it in config/storage.rb.\nremote_state_dynamodb table_name: \u0026#39;mytable\u0026#39;, region: \u0026#39;us-east-1\u0026#39;, force_creation: true, halt_on_error: true, locking: false These are the parameters:\ntable_name The name of the DynamoDB table to use. region The AWS region that the database is located force_creation Creates the DynamoDB table if it does not already exist halt_on_error Similar to the way Local State works, setting this to false will silence any errors in connecting to the DynamoDB table. Instead, your application will simply have access to an empty hash that does not get persisted anywhere. This is good for use cases that involve using this storage as a cache, where a connection error might mean the feature doesn\u0026rsquo;t work but its not important enough to interrupt the user. locking Setting this to true enables locking, meaning only one instance of your application can access the shared data at any given time. For more information see Distributed State Locking. Access and Usage Once configured you can access it with a standard hash syntax:\nRbcli.remote_state[:yourkeyhere] This works the same way that Local State does, with the same performance caveats (try not to write too frequently).\nNote that all state in Rbcli is lazy-loaded, so no connections will be made until your code attempts to access the data even if the feature is enabled.\nFor more information on the available commands, see the documentation on Local State\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/advanced/user_config_files/",
 	"title": "User Configuration Files",
 	"tags": [],
 	"description": "",
-	"content": "RBCli provides built-in support for creating and managing userspace configuration files. It does this through two chains: the defaults chain and the user chain.\nDefaults chain The defaults chain allows you to specify sane defaults for your CLI tool throughout your code. This gives you the ability to declare configuration alongside the code, and allows RBCli to generate a user config automatically given your defaults. There are two ways to set them:\n YAML Files  You can store your defaults in one or more YAML files and RBCli will import and combine them. Note that when generating the user config, RBCli will use the YAML text as-is, so comments are transferred as well. This allows you to write descriptions for the options directly in the file that the user can see. This is good for tools with large or complex configuration that needs user documentation written inline These YAML files should be placed in the userconf/ directory in your project and they will automatically be loaded   DSL Statements  In the DSL, you can specify options individually by providing a name, description, and default value This is good for simpler configuration, as the descriptions provided are written out as comments in the generated user config You can put global configuration options in config/userspace.rb Command-specific confiugration can be placed in the command declarations in application/commands/*.rb    DSL statements appear in both of the above locations as the following:\nconfig_default :name, description: \u0026#39;\u0026lt;description_help_text\u0026gt;\u0026#39;, default: \u0026#39;\u0026lt;default_value\u0026gt;\u0026#39; User chain The user chain has two functions: generating and loading configuration from a YAML file on the end user\u0026rsquo;s machine.\nRbcli will determine the correct location to locate the user configuration based on two factors:\n The default location set in config/userspace.rb The location specified on the command line using the --config-file=\u0026lt;filename\u0026gt; option (overrides #1)  To configure the default location, edit config/userspace.rb:\nconfig_userfile \u0026#39;~/.mytool\u0026#39;, merge_defaults: true, required: false  path/to/config/file  Self explanatory. Recommended locations are a dotfile in the user\u0026rsquo;s home directory, or a file under /etc such as /etc/mytool/userconf.yaml   merge_defaults  If set to true, default settings override user settings. If set to false, default settings are not loaded at all and the user is required to have all values specified in their config.   required  If set to true the application will not run if the file does not exist. A message will be displayed to the user to run your application with the --generate-config option to generate the file given your specified defaults.    Users can generate configs by running yourclitool --generate-config. This will generate a config file at the tool\u0026rsquo;s default location specified in the DSL. This location can be overridden via the --config-file=\u0026lt;filename\u0026gt; option.\n"
+	"content": "RBCli provides built-in support for creating and managing userspace configuration files. It does this through two chains: the defaults chain and the user chain.\nDefaults chain The defaults chain allows you to specify sane defaults for your CLI tool throughout your code. This gives you the ability to declare configuration alongside the code, and allows RBCli to generate a user config automatically given your defaults. There are two ways to set them:\nYAML Files You can store your defaults in one or more YAML files and RBCli will import and combine them. Note that when generating the user config, RBCli will use the YAML text as-is, so comments are transferred as well. This allows you to write descriptions for the options directly in the file that the user can see. This is good for tools with large or complex configuration that needs user documentation written inline These YAML files should be placed in the userconf/ directory in your project and they will automatically be loaded DSL Statements In the DSL, you can specify options individually by providing a name, description, and default value This is good for simpler configuration, as the descriptions provided are written out as comments in the generated user config You can put global configuration options in config/userspace.rb Command-specific confiugration can be placed in the command declarations in application/commands/*.rb DSL statements appear in both of the above locations as the following:\nconfig_default :name, description: \u0026#39;\u0026lt;description_help_text\u0026gt;\u0026#39;, default: \u0026#39;\u0026lt;default_value\u0026gt;\u0026#39; User chain The user chain has two functions: generating and loading configuration from a YAML file on the end user\u0026rsquo;s machine.\nRbcli will determine the correct location to locate the user configuration based on two factors:\nThe default location set in config/userspace.rb The location specified on the command line using the --config-file=\u0026lt;filename\u0026gt; option (overrides #1) To configure the default location, edit config/userspace.rb:\nconfig_userfile \u0026#39;~/.mytool\u0026#39;, merge_defaults: true, required: false path/to/config/file Self explanatory. Recommended locations are a dotfile in the user\u0026rsquo;s home directory, or a file under /etc such as /etc/mytool/userconf.yaml merge_defaults If set to true, default settings override user settings. If set to false, default settings are not loaded at all and the user is required to have all values specified in their config. required If set to true the application will not run if the file does not exist. A message will be displayed to the user to run your application with the --generate-config option to generate the file given your specified defaults. Users can generate configs by running yourclitool --generate-config. This will generate a config file at the tool\u0026rsquo;s default location specified in the DSL. This location can be overridden via the --config-file=\u0026lt;filename\u0026gt; option.\n"
 },
 {
 	"uri": "https://akhoury6.github.io/rbcli/categories/",