{"__v":0,"_id":"5821f11063e87b25000cbcbe","category":{"version":"5821f10e63e87b25000cbc90","project":"570e9147a5da5e0e005fdec3","_id":"5821f10e63e87b25000cbc95","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-14T17:39:57.939Z","from_sync":false,"order":4,"slug":"walkthroughs","title":"Tutorials"},"parentDoc":null,"project":"570e9147a5da5e0e005fdec3","user":"570fbbbe2fd5441900f799d1","version":{"__v":1,"_id":"5821f10e63e87b25000cbc90","project":"570e9147a5da5e0e005fdec3","createdAt":"2016-11-08T15:36:46.296Z","releaseDate":"2016-11-08T15:36:46.296Z","categories":["5821f10e63e87b25000cbc91","5821f10e63e87b25000cbc92","5821f10e63e87b25000cbc93","5821f10e63e87b25000cbc94","5821f10e63e87b25000cbc95","5821f10e63e87b25000cbc96","5821f10e63e87b25000cbc97","5821f10e63e87b25000cbc98","5821f10e63e87b25000cbc99","5821f10e63e87b25000cbc9a","5821f10e63e87b25000cbc9b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.16.0","version":"0.16"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-20T12:23:00.395Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Depreciated Content\",\n  \"body\": \"This documentation section has been deprecated, but we've got a better one already written! Please refer to the [Installing Your First Command Bundle](https://cog-book.operable.io/#_installing_your_first_command_bundle) section of The Cog Book for up to date information.\\n\\nThanks!\\n\\nOperable Team\"\n}\n[/block]\nSo you've installed Cog, you have a relay instance up and running and `cogctl` ready to go. Now what to do? Well, if your answer is, \"I'd like to install a bundle!\" then read on, you have come to the right place.\n\ntl;dr\nBundle installation is pretty simple once you have everything you need. In short there are only three primary steps. First you create the bundle, next we assign the new bundle to a relay and last we enable it.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Shortcuts\",\n  \"body\": \"Note that there are some extra flags that can be passed to `cogctl bundle install` that can shortcut some of the steps here. Namely the `--enable` and `--relay-groups` flags. Check out [Managing Bundles](doc:managing-bundles) to learn more.\"\n}\n[/block]\n# Creating your bundle\n\nIn order to create a bundle you only need one thing, a bundle config. Bundle configs are formatted in YAML and supply Cog with all the information it needs to install and execute commands in you bundle. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Bundle Configs\",\n  \"body\": \"To get all the nitty gritty about bundle configs go to the [Bundle Configs](doc:bundle-configs) section in the docs.\"\n}\n[/block]\nFor our example we will be using the following config. It's a simple bundle with only one un-enforcing command. Just create a file named `my_bundle.yaml` and paste the contents below into it. It doesn't actually matter what you name the file, just make sure that it is properly formatted YAML and that it has the correct extension, `.yaml` or `.yml`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"---\\nname: my_bundle\\nversion: \\\"0.1\\\"\\ncog_bundle_version: 3\\ncommands:\\n\\tdate:\\n  \\texecutable: /bin/date\\n    rules:\\n    - \\\"allow\\\"\",\n      \"language\": \"yaml\",\n      \"name\": \"my_bundle.yaml\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Command Rules\",\n  \"body\": \"If your commands specify any rules, other than the special \\\"allow\\\" rule, you will need to make sure the proper grants are in place. Check out [Permissions & Rules](doc:a-tour-through-cogs-authorization-system) to learn more.\"\n}\n[/block]\nOk, so now that we have our config file ready, let's create that bundle.\n\nBundles are most easily created with Cog's command line interface, `cogctl`. To create your bundle just type the following at the command prompt. Adjust the `my_bundle.yaml` bit to point to the config file that you created.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ cogctl bundle install my_bundle.yaml\",\n      \"language\": \"text\",\n      \"name\": \"Bash\"\n    }\n  ]\n}\n[/block]\nAnd there you have it! Bundle created. Now let's see about assigning it to a relay.\n\n# Assigning your bundle to a relay\n\nBundles are assigned to relays via relay groups. To learn more about relays and relay groups check out [Installing & Managing Relays](doc:installing-managing-relays). For the sake of this exercise we'll assume that you already have a relay group created, 'my_relay_group', and that it has at least one relay as a member.\n\nOnce again we can use `cogctl` to assign bundles to relay groups.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ cogctl relay-groups assign my_relay_group --bundles my_bundle\\nBundle `my_bundle` assigned to relay group `my_relay_group`\",\n      \"language\": \"text\",\n      \"name\": \"Bash\"\n    }\n  ]\n}\n[/block]\n\n# Enabling your bundle\n\nBy default any bundles added to Cog are added in the 'disabled' state. This way you don't have to worry about accidentally exposing commands that aren't fully configured, or otherwise un-ready for prime time.\n\nEnabling commands is easy though. We'll use `cogctl`! I betcha didn't see that one coming :) By default the highest installed version of a bundle will be enabled. To enable a different version just pass the version to enable to cogctl.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ cogctl bundle enable my_bundle\\n\\n$ cogctl bundle enable my_bundle 0.2.0\",\n      \"language\": \"text\",\n      \"name\": \"Bash\"\n    }\n  ]\n}\n[/block]\n\n# Profit!\n\nI know I said there were only three steps. And technically there are, but I have a thing for the whole \"last step == PROFIT!!\" thing.\n\nFor real though, that's it. You have successfully installed your first bundle. If everything went properly you should see the new command in Cog's help and be able to run it. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"User:\\n!help\\n\\nCog:\\nI know about these commands:\\n\\n * my_bundle:date\\n * operable:alias\\n * operable:bundle\\n * operable:echo\\n * operable:filter\\n * operable:greet\\n * operable:group\\n * operable:help\\n * operable:max\\n * operable:min\\n * operable:permissions\\n * operable:raw\\n * operable:role\\n * operable:rules\\n * operable:seed\\n * operable:sleep\\n * operable:sort\\n * operable:sum\\n * operable:table\\n * operable:thorn\\n * operable:unique\\n * operable:wc\\n * operable:which\\n\\n Try calling `operable:help COMMAND` to find out more.\\n \\n User:\\n !date\\n \\n Cog:\\n Tue Mar 29 18:07:41 EDT 2016\",\n      \"language\": \"text\",\n      \"name\": \"Cog\"\n    }\n  ]\n}\n[/block]","excerpt":"Might be some good info to have","slug":"installing-your-first-command-bundle","type":"basic","title":"Installing Your First Command Bundle"}

Installing Your First Command Bundle

Might be some good info to have

[block:callout] { "type": "danger", "title": "Depreciated Content", "body": "This documentation section has been deprecated, but we've got a better one already written! Please refer to the [Installing Your First Command Bundle](https://cog-book.operable.io/#_installing_your_first_command_bundle) section of The Cog Book for up to date information.\n\nThanks!\n\nOperable Team" } [/block] So you've installed Cog, you have a relay instance up and running and `cogctl` ready to go. Now what to do? Well, if your answer is, "I'd like to install a bundle!" then read on, you have come to the right place. tl;dr Bundle installation is pretty simple once you have everything you need. In short there are only three primary steps. First you create the bundle, next we assign the new bundle to a relay and last we enable it. [block:callout] { "type": "info", "title": "Shortcuts", "body": "Note that there are some extra flags that can be passed to `cogctl bundle install` that can shortcut some of the steps here. Namely the `--enable` and `--relay-groups` flags. Check out [Managing Bundles](doc:managing-bundles) to learn more." } [/block] # Creating your bundle In order to create a bundle you only need one thing, a bundle config. Bundle configs are formatted in YAML and supply Cog with all the information it needs to install and execute commands in you bundle. [block:callout] { "type": "info", "title": "Bundle Configs", "body": "To get all the nitty gritty about bundle configs go to the [Bundle Configs](doc:bundle-configs) section in the docs." } [/block] For our example we will be using the following config. It's a simple bundle with only one un-enforcing command. Just create a file named `my_bundle.yaml` and paste the contents below into it. It doesn't actually matter what you name the file, just make sure that it is properly formatted YAML and that it has the correct extension, `.yaml` or `.yml`. [block:code] { "codes": [ { "code": "---\nname: my_bundle\nversion: \"0.1\"\ncog_bundle_version: 3\ncommands:\n\tdate:\n \texecutable: /bin/date\n rules:\n - \"allow\"", "language": "yaml", "name": "my_bundle.yaml" } ] } [/block] [block:callout] { "type": "warning", "title": "Command Rules", "body": "If your commands specify any rules, other than the special \"allow\" rule, you will need to make sure the proper grants are in place. Check out [Permissions & Rules](doc:a-tour-through-cogs-authorization-system) to learn more." } [/block] Ok, so now that we have our config file ready, let's create that bundle. Bundles are most easily created with Cog's command line interface, `cogctl`. To create your bundle just type the following at the command prompt. Adjust the `my_bundle.yaml` bit to point to the config file that you created. [block:code] { "codes": [ { "code": "$ cogctl bundle install my_bundle.yaml", "language": "text", "name": "Bash" } ] } [/block] And there you have it! Bundle created. Now let's see about assigning it to a relay. # Assigning your bundle to a relay Bundles are assigned to relays via relay groups. To learn more about relays and relay groups check out [Installing & Managing Relays](doc:installing-managing-relays). For the sake of this exercise we'll assume that you already have a relay group created, 'my_relay_group', and that it has at least one relay as a member. Once again we can use `cogctl` to assign bundles to relay groups. [block:code] { "codes": [ { "code": "$ cogctl relay-groups assign my_relay_group --bundles my_bundle\nBundle `my_bundle` assigned to relay group `my_relay_group`", "language": "text", "name": "Bash" } ] } [/block] # Enabling your bundle By default any bundles added to Cog are added in the 'disabled' state. This way you don't have to worry about accidentally exposing commands that aren't fully configured, or otherwise un-ready for prime time. Enabling commands is easy though. We'll use `cogctl`! I betcha didn't see that one coming :) By default the highest installed version of a bundle will be enabled. To enable a different version just pass the version to enable to cogctl. [block:code] { "codes": [ { "code": "$ cogctl bundle enable my_bundle\n\n$ cogctl bundle enable my_bundle 0.2.0", "language": "text", "name": "Bash" } ] } [/block] # Profit! I know I said there were only three steps. And technically there are, but I have a thing for the whole "last step == PROFIT!!" thing. For real though, that's it. You have successfully installed your first bundle. If everything went properly you should see the new command in Cog's help and be able to run it. [block:code] { "codes": [ { "code": "User:\n!help\n\nCog:\nI know about these commands:\n\n * my_bundle:date\n * operable:alias\n * operable:bundle\n * operable:echo\n * operable:filter\n * operable:greet\n * operable:group\n * operable:help\n * operable:max\n * operable:min\n * operable:permissions\n * operable:raw\n * operable:role\n * operable:rules\n * operable:seed\n * operable:sleep\n * operable:sort\n * operable:sum\n * operable:table\n * operable:thorn\n * operable:unique\n * operable:wc\n * operable:which\n\n Try calling `operable:help COMMAND` to find out more.\n \n User:\n !date\n \n Cog:\n Tue Mar 29 18:07:41 EDT 2016", "language": "text", "name": "Cog" } ] } [/block]