snapctl 1.0.4__tar.gz → 1.1.1__tar.gz

{snapctl-1.0.4 → snapctl-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: snapctl
-Version: 1.0.4
+Version: 1.1.1
 Summary: Snapser CLI Tool
 Author: Ajinkya Apte
 Author-email: aj@snapser.com
@@ -232,7 +232,27 @@ Run the following to see the list of commands Snapser supports
 snapctl --help
 ```
 
-### BYO Snap - Bring your own Snap
+### 1. Snaps
+Snapctl commands for snaps
+
+#### 1. snaps help
+See all the supported commands.
+
+```bash
+# Help for the byosnap command
+snapctl snaps --help
+```
+
+#### 2. snaps enumerate
+See all the supported commands.
+
+```bash
+# Enumerate details for all the available snaps
+# $output_path = Optional path to where you want snapctl to save snap details
+snapctl snaps enumerate --out-path
+```
+
+### 2. BYO Snap - Bring your own Snap
 Snapctl commands for your custom code
 
 #### 1. byosnap help
@@ -463,7 +483,7 @@ snapctl byosnap publish-version --help
 snapctl byosnap publish-version --byosnap-id $byosnap_id --tag $image_tag --version $version --path $byosnap_profile_path
 ```
 
-### BYO Workstation - Bring your own Workstation
+### 3. BYO Workstation - Bring your own Workstation
 Snapctl commands for bring your own workstation. This command allows you to attach your workstation to a Snapend. This is useful for testing and debugging your BYOSnap code.
 
 #### 1. byows help
@@ -494,7 +514,7 @@ source ~/.snapser/byows_env_setup.sh
 
 Then start your BYOSnap local server in the same tab that has the environment variables set up. This will ensure that the BYOSnap code can access the internal SDK and other Snaps in your Snapend.
 
-### BYO Game Server - Bring your own Game Server
+### 4. BYO Game Server - Bring your own Game Server
 Snapctl commands for your custom game server
 
 #### 1. byogs help
@@ -582,32 +602,133 @@ snapctl byogs push --help
 snapctl byogs push --tag $image_tag
 ```
 
+### 5. Application
+Snapctl commands for your application
+
+#### 1. application help
+
+See all the supported commands
+
+```bash
+# Help for the byogs command
+snapctl application --help
+```
+
+#### 2. application create
+Create an application
+```bash
+snapctl application create --name $app_name
+```
 
-### Game
-Snapctl commands for your game
+#### 3. application enumerate
+List all the applications
+```bash
+snapctl application enumerate
+```
 
-#### 1. game help
+### 6. Snapend Manifest
+Snapctl commands for the Snapend manifest. Manifest is the representation of your Snapser backend
+stored as a JSON or YAML. The manifest can then be used to create, update your backend.
+
+#### 1. snapend-manifest help
 
 See all the supported commands
 
 ```bash
 # Help for the byogs command
-snapctl game --help
+snapctl snapend-manifest --help
 ```
 
-#### 2. game create
-Create a game
+#### 2. Snapend Manifest Create
+
+Create a Snapend manifest. It should be noted that the latest versions of the snap at the time of running the command is what gets added to the manifest. For example, say the `analytics` snap has versions `v1.0.0`, `v1.1.0` available on the web portal. If you run the create command with `--snaps analytics` the `v1.1.0` which is the latest at that moment in time, gets added to your manifest.
+
+The output manifest file can then be used with the `snapend create` or `snapend clone` commands.
+
 ```bash
-snapctl game create --name $game_name
+# Create a Snapend manifest file
+# $name = Name for your backend, which is stored in the outputted manifest
+# $env = One of DEVELOPMENT, STAGING or PRODUCTION
+# $output_path_filename = Path and file name to store the manifest. The filename should end with .json or .yaml
+# $snaps = Comma separated list of snap ids you want to add.  You can get the snap ids from the
+#     `snapctl snaps enumerate --out-path ./snaps.json` command
+# $features = Pass `WEB_SOCKETS` if you want to enable web sockets for your backend.
+# Note: One of snaps or features is required
+# Example:
+#   snapend-manifest create --name my-dev-snapend --env DEVELOPMENT --snaps auth,analytics --add-features WEB_SOCKETS --out-path ./snapend-manifest.json
+
+snapctl snapend-manifest create --name $name --env $env --snaps $snaps --features $features --out-path-filename $output_path_filename
 ```
 
-#### 3. game enumerate
-List all the games
+#### 3. Snapend Manifest Sync
+
+Sync with an existing Snapend manifest. This command is idempotent and destructive.
+
+- It ensures the input manifest gets replaced with the values you pass in `--snaps` and `--features`. For example: If your input manifest has a snap but you do not pass the snap in the `--snaps`, it will be removed from the output. Same goes for `--features`.
+- Additionally, if a snap is present in the manifest and you pass it in as part of `--snaps` it will not be touched. But if a snap is not part of the manifest and you pass it in as part of `--snaps` it will be added with the latest version of the snap. For example, say the `analytics` snap has versions `v1.0.0`, `v1.1.0` available on the web portal. If you run the sync command with `--snaps analytics` and you had `v1.0.0` in the manifest then it wont be touched. However, if you did not have it in the manifest then the `v1.1.0` which is the latest at that moment in time, gets added to your manifest.
+
+**IMPORTANT**: If you are looking for a command to purely add or remove snaps or features, consider using the `update` command instead.
+
 ```bash
-snapctl game enumerate
+# Sync a Snapend manifest file
+# $input_manifest = Path and file name of the current manifest. The filename should end with .json or .yaml
+# $output_path_filename = Path and file name to store the manifest. The filename should end with .json or .yaml
+# $snaps = Comma separated list of snap ids you want to have at the end. You can get the snap ids from # the `snapctl snaps enumerate --out-path ./snaps.json` command.
+#   IMPORTANT: If your manifest has a snap but your --snaps does not. It will be removed.
+# $features = Pass `WEB_SOCKETS` if you want to enable web sockets for your backend.
+#   IMPORTANT: If your manifest has a feature but your --features does not. It will be removed.
+# Note: One of snaps, and features is required
+# Example:
+#   snapctl snapend-manifest sync --manifest-path-filename ./snapser-jn86b0dv-manifest.yaml --add-snaps game-server-fleets --remove-snaps analytics --remove-features WEB_SOCKETS --out-path ./snapend-updated-manifest.yaml
+
+snapctl snapend-manifest update --manifest-path-filename $input_manifest --snaps $snaps --features $features--out-path-filename $output_path_filename
 ```
 
-### Snapend
+#### 4. Snapend Manifest Upgrade
+
+Upgrade all snaps or a list of snaps to the latest version of the snap available at that moment in time. If you do not pass in `--snaps` then all the snaps in the manifest will be upgraded. If you do pass a list of snaps then all snap Ids are expected to be valid.
+
+```bash
+# Update a Snapend manifest file
+# $input_manifest = Path and file name of the current manifest. The filename should end with .json or .yaml
+# $output_path_filename = Path and file name to store the manifest. The filename should end with .json or .yaml
+# $snaps = (Optional) Comma separated list of snap ids you want to upgrade. You can get the snap ids
+#   from the `snapctl snaps enumerate --out-path ./snaps.json` command
+#   IMPORTANT: If the --snaps parameter is not provided then all snaps in the manifest will be upgraded
+# Example:
+# snapctl snapend-manifest upgrade --manifest-path-filename ./snapser-jn86b0dv-manifest.yaml --snaps game-server-fleets --out-path ./snapend-updated-manifest.yaml
+# snapctl snapend-manifest upgrade --manifest-path-filename ./snapser-jn86b0dv-manifest.yaml --out-path ./snapend-updated-manifest.yaml
+
+snapctl snapend-manifest upgrade --manifest-path-filename $input_manifest --out-path-filename $output_path_filename
+
+snapctl snapend-manifest upgrade --manifest-path-filename $input_manifest --snaps $snaps --out-path-filename $output_path_filename
+```
+
+#### 5. Snapend Manifest Update
+
+Update your manifest. This command is additive and subtractive. It allows you to add or remove, snaps and features from an existing manifest. Unlike `sync`, this will only add or remove entities from your manifest, keeping the remaining part of the manifest intact. If your manifest has a snap and you pass it with `--add-snaps` then it will be ignored. However if you do not have a snap and you pass it with `--add-snaps` then the latest version of the snap will be added. If you pass a snap with `--remove-snaps` that is already not in the manifest, then it will be skipped. This ensures idempotency after the initial update is made to the snapend manifest.
+
+**IMPORTANT**:
+- All additions are performed before removals.
+- If you are looking to have strict relation between your input (snaps + features) and your output manifest, consider using the `sync` command.
+
+```bash
+# Update a Snapend manifest file
+# $input_manifest = Path and file name of the current manifest. The filename should end with .json or .yaml
+# $output_path_filename = Path and file name to store the manifest. The filename should end with .json or .yaml
+# $addSnaps = Comma separated list of snap ids you want to add to your manifest. You can get the snap ids from # the `snapctl snaps enumerate --out-path ./snaps.json` command.
+# $removeSnaps = Comma separated list of snap ids you want to remove from your manifest. You can get the snap ids from # the `snapctl snaps enumerate --out-path ./snaps.json` command.
+# $addFeatures = Pass `WEB_SOCKETS` if you want to enable web sockets for your backend.
+# $removeFeatures = Pass `WEB_SOCKETS` if you want to disable web sockets for your backend.
+# Note: One of add-snaps, remove-snaps, add-features or remove-features is required
+# Example:
+#   snapctl snapend-manifest update --manifest-path-filename ./snapser-jn86b0dv-manifest.yaml --add-snaps game-server-fleets --remove-snaps analytics --remove-features WEB_SOCKETS --out-path ./snapend-updated-manifest.yaml
+
+snapctl snapend-manifest update --manifest-path-filename $input_manifest --add-snaps $addSnaps --remove-snaps $removeSnaps --add-features $addFeatures --remove-features $removeFeatures --out-path-filename $output_path_filename
+```
+
+
+### 7. Snapend
 Snapctl commands for your snapend
 
 #### 1. snapend help
@@ -653,7 +774,26 @@ snapctl snapend download --snapend-id $snapend_id --category $category --format
 snapctl snapend download --snapend-id $snapend_id --category $category --format $format --type $type --http-lib $http_lib --out-path $out_path
 ```
 
-#### 3. snapend clone
+#### 3. snapend create
+
+Create a Snapend from an existing manifest. Passing the blocking flag ensures your CLI command waits till the new Snapend is up.
+
+```bash
+# Help for the crete command
+snapctl snapend create --help
+
+# Create a Snapend
+# $app_id = App Id
+# $path_to_manifest = Path to the manifest file; should include the file name
+# Optionally override name and environment by passing the --name and --environment overrides
+# Example:
+# snapctl snapend create --manifest-path-filename $path_to_manifest --app-id $app_id  --blocking
+snapctl snapend create --manifest-path-filename $path_to_manifest --app-id $app_id
+snapctl snapend create --manifest-path-filename $path_to_manifest --app-id $app_id --blocking
+snapctl snapend create --name $name --env $env --manifest-path-filename $path_to_manifest --app-id $app_id --blocking
+```
+
+#### 4. snapend clone
 
 Clone a Snapend from an existing manifest. Passing the blocking flag ensures your CLI command waits till the new Snapend is up.
 
@@ -662,17 +802,17 @@ Clone a Snapend from an existing manifest. Passing the blocking flag ensures you
 snapctl snapend clone --help
 
 # Clone your Snapend
-# $game_id = Game Id
+# $app_id = App Id
 # $snapend_name = Name of your new Snapend
 # $env = One of development, staging
 # $path_to_manifest = Path to the manifest file; should include the file name
 # Example:
-# snapctl snapend clone --game-id 2581d802-aca-496c-8a76-1953ad0db165 --name new-snapend --env development --manifest-path-filename "C:\Users\name\Downloads\snapser-ox1bcyim-manifest.json" --blocking
-snapctl snapend clone --game-id $game_id --name $snapend_name --env $env --manifest-path-filename "$path_to_manifest"
-snapctl snapend clone --game-id $game_id --name $snapend_name --env $env --manifest-path-filename "$path_to_manifest" --blocking
+# snapctl snapend clone --app-id 2581d802-aca-496c-8a76-1953ad0db165 --name new-snapend --env development --manifest-path-filename "C:\Users\name\Downloads\snapser-ox1bcyim-manifest.json" --blocking
+snapctl snapend clone --app-id $app_id --name $snapend_name --env $env --manifest-path-filename "$path_to_manifest"
+snapctl snapend clone --app-id $app_id --name $snapend_name --env $env --manifest-path-filename "$path_to_manifest" --blocking
 ```
 
-#### 4. snapend apply
+#### 5. snapend apply
 
 Apply changes to your Snapend from a manifest. You should have the latest manifest before applying changes. Basically, when you download a manifest, Snapser adds an `applied_configuration` section to your manifest, which stores the state of the Snapend during export. Now, if someone manually updates the Snapend or a configuration of a Snap, you are no longer going to have the latest Snapend representation in the `applied_configuration`. This is how Snapser prevents you from stomping over someone elses changes.
 
@@ -695,7 +835,7 @@ snapctl snapend apply --manifest-path-filename "$path_to_manifest" --blocking
 snapctl snapend apply --manifest-path-filename "$path_to_manifest" --force --blocking
 ```
 
-#### 5. snapend update
+#### 6. snapend update
 
 Update your BYOSnap or BYOGs versions for the Snapend
 
@@ -715,7 +855,7 @@ snapctl snapend update --help
 snapctl snapend update --snapend-id $snapend_id --byosnaps $byosnaps --byogs $byogs --blocking
 ```
 
-#### 6. snapend state
+#### 7. snapend state
 
 Get the Snapend state
 
@@ -730,7 +870,7 @@ snapctl snapend state --help
 snapctl snapend state $snapend_id
 ```
 
-### Generate
+### 8. Generate
 Generator tool to help generate credentials
 
 #### 1. generate help
@@ -757,6 +897,7 @@ snapctl generate credentials --category "ecr" --out-path $output_path
 | 1          | General error                                            |
 | 2          | Input error                                              |
 | 3          | Resource not found                                       |
+| 4          | Internal server error                                    |
 
 ### Configuration Errors
 | Error Code | Description                                              |
@@ -765,10 +906,23 @@ snapctl generate credentials --category "ecr" --out-path $output_path
 | 11         | Configuration error                                      |
 | 12         | Dependency missing                                       |
 
+### Snaps Errors
+| Error Code | Description                                              |
+|------------|----------------------------------------------------------|
+| 13         | Snaps Generic error                                      |
+| 14         | Snaps Enumerate error                                    |
+
+### Snapend Manifest Errors
+| Error Code | Description                                              |
+|------------|----------------------------------------------------------|
+| 16         | Snapend Manifest create error                            |
+| 17         | Snapend Manifest update error                            |
+| 18         | Snapend Manifest upgrade error                           |
+
 ### BYOGS Errors
 | Error Code | Description                                              |
 |------------|----------------------------------------------------------|
-| 3          | BYOGs resource not found                                 |
+| 3          | Resource not found: BYOGs resource not found             |
 | 20         | Generic BYOGS error                                      |
 | 21         | BYOGS dependency missing                                 |
 | 22         | BYOGS ECR login error                                    |
@@ -781,7 +935,7 @@ snapctl generate credentials --category "ecr" --out-path $output_path
 ### BYOSNAP Errors
 | Error Code | Description                                              |
 |------------|----------------------------------------------------------|
-| 3          | BYOSnap resource not found                               |
+| 3          | Resource not found: BYOSnap resource not found           |
 | 30         | Generic BYOSNAP error                                    |
 | 31         | BYOSNAP dependency missing                               |
 | 32         | BYOSNAP ECR login error                                  |
@@ -806,21 +960,21 @@ snapctl generate credentials --category "ecr" --out-path $output_path
 | 87         | BYOSNAP swagger error                                    |
 
 
-### Game Errors
+### Application Errors
 | Error Code | Description                                              |
 |------------|----------------------------------------------------------|
-| 3          | Game resource not found                                  |
-| 50         | Generic game error                                       |
-| 51         | Game create error                                        |
-| 52         | Game create permission error                             |
-| 53         | Game create limit error                                  |
-| 54         | Game create duplicate name error                         |
-| 55         | Game enumerate error                                     |
+| 3          | Resource not found: Application resource not found       |
+| 50         | Generic application error                                |
+| 51         | Application create error                                 |
+| 52         | Application create permission error                      |
+| 53         | Application create limit error                           |
+| 54         | Application create duplicate name error                  |
+| 55         | Application enumerate error                              |
 
 ### Snapend Errors
 | Error Code | Description                                              |
 |------------|----------------------------------------------------------|
-| 3          | Snapend resource not found                               |
+| 3          | Resource not found: Snapend resource not found           |
 | 60         | Generic snapend error                                    |
 | 61         | Snapend enumerate error                                  |
 | 62         | Snapend clone error                                      |
@@ -838,6 +992,9 @@ snapctl generate credentials --category "ecr" --out-path $output_path
 | 74         | Snapend update timeout error                             |
 | 75         | Snapend state error                                      |
 | 76         | Snapend manifest mismatch error                          |
+| 77         | Snapend create error                                     |
+| 78         | Snapend create server error                              |
+| 79         | Snapend create timeout error                             |
 
 ### Generate Errors
 | Error Code | Description                                              |