snapctl 0.48.0__tar.gz → 0.49.0__tar.gz

{snapctl-0.48.0 → snapctl-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: snapctl
-Version: 0.48.0
+Version: 0.49.0
 Summary: Snapser CLI Tool
 Author: Ajinkya Apte
 Author-email: aj@snapser.com
@@ -18,30 +18,27 @@ Requires-Dist: requests (>=2.28.2,<3.0.0)
 Requires-Dist: typer[all] (>=0.12.3,<0.13.0)
 Description-Content-Type: text/markdown
 
+export const description = 'CLI'
+
+export const meta = {
+  author: 'AJ Apte',
+}
+
 # Snapser CLI
 
 Snapser has developed a CLI tool called **snapctl** that can be used on MaxOSX, Linux and Windows machines.
 Snapctl will be the best way for game studios to integrate Snapser into their build pipelines.
 
 ## What's new in the latest version?
+### Breaking Changes
+1. Renamed SDK type `server` to `api-key` to be consistent with the Snapser Web app.
+
 ### Features
-1. Dockerfile can now be present either at the root or the resources path. Snapctl will automatically look for the Dockerfile in both locations.
-2. Snapctl now throws a better warning when the swagger for the BYOSnap is not compatible with what the Snapser backed expects. You will get a warning message:
-```bash
-Warning Snapser enforces a strict schema for the swagger.json file. It needs to be a valid OpenAPI 3.0 spec. In addition, ever API needs an operationId. a summary and
-a non-empty description. This allows Snapser to generate your SDK and power the API explorer. If you do not wish to leverage this feature, just remove the
-swagger.json file.
-```
-3. You can now use the `--skip-build` flag with the snapctl sync command. This allows you to skip the build step when syncing your Snapend resources.
+1. Added support for Bring your own Workstation commands.
 ```bash
-byosnap sync --snapend-id $snapendId --byosnap-id $byosnapId --version $version --path $path --skip-build
+snapctl byows attach --snapend-id $snapend_id --byosnap-id $byosnap_id --http-port $http_port
 ```
 
-### Fixes
-1. Snapctl was failing if the user passed in a tag with a `:` in it. This has been fixed. It now checks for the presence of a `:` in the tag and throws an error in the input validation step.
-2. The byosnap generate command was failing. This has been fixed.
-
-
 ## Requirements
 ### Python 3.X and Pip
 The Snapser CLI tool depends on Python 3.X and Pip. MacOS comes pre installed with Python. But
@@ -59,6 +56,7 @@ cause issues with the Snapser CLI tool.
 
 ## Installation
 
+### Pip
 Installing PIP on MacOS
 
 ```
@@ -73,29 +71,48 @@ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
 python get-pip.py
 ```
 
-Once you have Python and Pip installed
-
+### Pipx
+Now a days, pipx is recommended for CLI tools. Once you have Python and Pip installed, lets install `Pipx`.
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
 ```
+
+### Install Snapctl
+ - If you chose to use Pip
+```bash
 pip install --user snapctl
 ```
 
 If you also have Python 2.X on your machine, you may have to run the following command instead
 
-```
+```bash
 pip3 install --user snapctl
 ```
+- If using, Pipx
+```bash
+pipx install snapctl
+```
 
 **IMPORTANT**: After you install snapctl you may have to add the python bin folder to your
 path. For example, on MacOSX this is usually **~/Library/Python/3.9/bin**. On
-Windows this is usually
-**C:\Users\username\AppData\Roaming\Python\Python39\Scripts**.
+Windows this is usually **C:\Users\username\AppData\Roaming\Python\Python39\Scripts**.
+For, Windows users, after running pipx ensurepath, you may need to restart your terminal (Command Prompt, PowerShell, or Windows Terminal) for the PATH changes to take effect.
+
 
 ## Upgrade
 
 Upgrade your snapctl version
 
+- If using Pip
+
+```bash
+pip3 install --user snapctl --upgrade
 ```
-pip install --user snapctl --upgrade
+
+- If using Pipx
+```bash
+pipx upgrade snapctl
 ```
 
 ## Setup
@@ -115,7 +132,7 @@ to see it again.
 You have three ways to pass the API key to Snapctl
 1. Pass it via a command line argument with every command
 2. Pass it via an environment variable
-3. Pass it via a config file
+3. Pass it via a config file (recommended)
 
 #### Command line argument
 
@@ -138,7 +155,7 @@ will look for the config file at that path.
 
 ```
 [default]
-snapser_access_key = $your_api_key
+SNAPSER_API_KEY=$your_api_key
 ```
 
 Or you can run the following command
@@ -174,10 +191,10 @@ Snapser by default supports access to multiple accounts. You can create multiple
 
 ```
 [profile personal]
-snapser_access_key = <key>
+nSNAPSER_API_KEY=<key>
 
 [profile professional]
-snapser_access_key = <key>
+nSNAPSER_API_KEY=<key>
 
 ```
 
@@ -195,7 +212,7 @@ setx SNAPSER_PROFILE="my_profile_name";
 
 ```
 
-Or you can pass **--profile my_profile_name** with every command to tell Snapser to use a particular profile.
+Or you can pass **--profile professional** with every command to tell Snapser to use a particular profile.
 
 ## Command variable name nomenclature
 All commands follow these rules with their input variables
@@ -216,15 +233,14 @@ Snapctl commands for your custom code
 
 #### 1. byosnap help
 
-See all the supported commands. You should mainly need the `publish` and `sync` commands.
-All the others are for CRUD operations.
+See all the supported commands.
 
 ```bash
 # Help for the byosnap command
 snapctl byosnap --help
 ```
 
-### 2. byosnap generate-profile
+#### 2. byosnap generate-profile
 
 This command generates a base BYOSnap profile. You will have to update the values within this file
 and then you can use it in commands like `publish` and `sync`. It is recommended that you save this
@@ -240,11 +256,11 @@ snapctl byosnap generate-profile --help
 #   are allowed. If you do not pass `--profile-filename` then Snapser choses
 #   `snapser-byosnap-profile.json` as the filename.
 snapctl byosnap generate-profile --out-path $output_path --profile-filename $profile_filename
-snapctl byosnap generate-profile --out-path /Users/DevName/Development/SnapserEngine/jinks_flask --profile-filename=my-byosnap-profile.json
-snapctl byosnap generate-profile --out-path /Users/DevName/Development/SnapserEngine/jinks_flask --profile-filename=my-byosnap-profile.yaml
+snapctl byosnap generate-profile --out-path /Users/DevName/Development/SnapserEngine/byosnap-python --profile-filename=my-byosnap-profile.json
+snapctl byosnap generate-profile --out-path /Users/DevName/Development/SnapserEngine/byosnap-python --profile-filename=my-byosnap-profile.yaml
 ```
 
-### 3. byosnap validate-profile
+#### 3. byosnap validate-profile
 
 This command validates your BYOSnap profile.
 
@@ -260,8 +276,8 @@ snapctl byosnap validate-profile --help
 #   Snapser choses the default `snapser-byosnap-profile.json` as the filename to validate
 snapctl byosnap validate-profile --path $path
 snapctl byosnap validate-profile --resources-path $resources_path --profile-filename $profile_filename
-snapctl byosnap validate-profile --path /Users/DevName/Development/SnapserEngine/jinks_flask
-snapctl byosnap validate-profile --path /Users/DevName/Development/SnapserEngine/jinks_flask --profile-filename my-byosnap-profile.yaml
+snapctl byosnap validate-profile --path /Users/DevName/Development/SnapserEngine/byosnap-python
+snapctl byosnap validate-profile --path /Users/DevName/Development/SnapserEngine/byosnap-python --profile-filename my-byosnap-profile.yaml
 ```
 
 #### 4. byosnap publish
@@ -291,7 +307,7 @@ snapctl byosnap publish --help
 #   Snapser choses the default `snapser-byosnap-profile.json` as the filename to validate
 # $skip-build = true/false. Default is false. Pass this flag as true to skip the build and head straight to tag and push. Build step needs to run and tag using the --tag you pass to the publish-image command for this to work. Make sure the tag matches the version number you are passing.
 # Example:
-snapctl byosnap publish --byosnap-id byosnap-jinks-flask --version "v0.0.1" --path /Users/DevName/Development/SnapserEngine/jinks_flask --profile-filename $profile_filename
+snapctl byosnap publish --byosnap-id byosnap-jinks-flask --version "v0.0.1" --path /Users/DevName/Development/SnapserEngine/byosnap-python --profile-filename $profile_filename
 snapctl byosnap publish --byosnap-id $byosnap_id --version $version --path $code_root_path
 byosnap publish --byosnap-id byosnap-python --version "v1.0.0" --path /Users/AJ/Development/byosnap-python --profile-filename my-byosnap-profile.yaml
 ```
@@ -318,7 +334,7 @@ snapctl byosnap sync --help
 # $version =
 # $snapend_id = Dev Snapend Id
 # Example:
-snapctl byosnap sync --byosnap-id byosnap-jinks-flask --path /Users/DevName/Development/SnapserEngine/jinks_flask --version "v0.0.11" --snapend-id "jxmmfryo"
+snapctl byosnap sync --byosnap-id byosnap-jinks-flask --path /Users/DevName/Development/SnapserEngine/byosnap-python --version "v0.0.11" --snapend-id "jxmmfryo"
 snapctl byosnap sync --byosnap-id $byosnap_id --path $code_root_path --version $version --snapend-id $snapend_id
 ```
 
@@ -357,7 +373,7 @@ snapctl byosnap build --help
 # $code_root_path = Local code path where your Dockerfile is present
 # $resources_path = Optional path to the resources directory in your Snap. This ensures, you are not forced to put the Dockerfile, swagger.json and README.md in the root directory of your Snap.
 # Example:
-# snapctl byosnap build --byosnap-id byosnap-jinks-flask --tag my-first-image --path /Users/DevName/Development/SnapserEngine/jinks_flask
+# snapctl byosnap build --byosnap-id byosnap-jinks-flask --tag my-first-image --path /Users/DevName/Development/SnapserEngine/byosnap-python
 snapctl byosnap build --byosnap-id $byosnap_id --tag $image_tag --path $code_root_path
 snapctl byosnap build --byosnap-id $byosnap_id --tag $image_tag --path $code_root_path --resources-path $resources_path
 ```
@@ -391,7 +407,7 @@ snapctl byosnap upload-docs --help
 # $image_tag = An image tag for your snap
 # $resources_path = Path to your swagger.json and README.md files
 # Example:
-# snapctl byosnap upload-docs --byosnap-id byosnap-jinks-flask --tag my-first-image --resources-path /Users/DevName/Development/SnapserEngine/jinks_flask
+# snapctl byosnap upload-docs --byosnap-id byosnap-jinks-flask --tag my-first-image --resources-path /Users/DevName/Development/SnapserEngine/byosnap-python
 snapctl byosnap upload-docs --byosnap-id $byosnap_id --tag $image_tag --resources-path $resources_path
 ```
 
@@ -415,7 +431,7 @@ snapctl byosnap publish-image --help
 # $resources_path = Optional path to the resources directory in your Snap. This ensures, you are not forced to put the Dockerfile, swagger.json and README.md in the root directory of your Snap.
 # $skip-build = true/false. Default is false. Pass this flag as true to skip the build and head straight to tag and push. Build step needs to run and tagged using the --tag you pass to the publish-image command for this to work.
 # Example:
-# snapctl byosnap publish-image --byosnap-id byosnap-jinks-flask --tag my-first-image --path /Users/DevName/Development/SnapserEngine/jinks_flask
+# snapctl byosnap publish-image --byosnap-id byosnap-jinks-flask --tag my-first-image --path /Users/DevName/Development/SnapserEngine/byosnap-python
 snapctl byosnap publish-image --byosnap-id $byosnap_id --tag $image_tag --path $code_root_path
 snapctl byosnap publish-image --byosnap-id $byosnap_id --tag $image_tag --path $code_root_path --resources-path $resources_path
 snapctl byosnap publish-image --byosnap-id $byosnap_id --tag $image_tag --skip-build
@@ -439,54 +455,54 @@ snapctl byosnap publish-version --help
 # $version = Semantic version for your snap Eg: v0.0.1
 # $byosnap_profile_path = Path to the snapser-byosnap-profile.json BYOSnap profile to configure dev, stage and prod settings for this snap. You can generate a base version of this file using the `snapctl byosnap generate-profile --out-path $outputPath --profile-filename $profileName` command
 # Example:
-# snapctl byosnap publish-version --byosnap-id byosnap-jinks-flask --tag my-first-image --version v0.0.1 --path /Users/DevName/Development/SnapserEngine/jinks_flask
+# snapctl byosnap publish-version --byosnap-id byosnap-jinks-flask --tag my-first-image --version v0.0.1 --path /Users/DevName/Development/SnapserEngine/byosnap-python
 snapctl byosnap publish-version --byosnap-id $byosnap_id --tag $image_tag --version $version --path $byosnap_profile_path
 ```
 
-### BYO Game Server - Bring your own Game Server
-Snapctl commands for your custom game server
-
-#### 1. byogs help
+### 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
 See all the supported commands
 
 ```bash
-# Help for the byogs command
-snapctl byogs --help
+# Help for the byows command
+snapctl byows --help
 ```
-
-#### 2. byogs build
-
-Build your custom game server image.
+#### 2. byows attach
+Attach your workstation to a Snapend. It should be noted, that this command outputs a file `byows_env_setup.sh|ps1` at `~/.snapser/` directory. This file contains the environment variables that the BYOWS technology will need to route internal calls to the appropriate Snaps.
 
 ```bash
-# Help for the byogs command
-snapctl byogs build --help
+# Attach your workstation to a Snapend
+# $snapend_id = Snapend Id
+# $byosnap_id = BYOSnap Id
+# $http_port = Port that your local server is running on
+snapctl byows attach --snapend-id $snapend_id --byosnap-id $byosnap_id --http-port $http_port
+```
 
-# Publish a new image
-# $image_tag = An image tag for your snap
-# $code_root_path = Local code path where your Dockerfile is present
-# Example:
-# snapctl byogs build byosnap-jinks-gs --tag my-first-image --path /Users/DevName/Development/SnapserEngine/game_server
-snapctl byogs build --tag $image_tag --path $code_root_path
+Then run, the following command in a separate terminal window, to setup the BYOWS environment variables.
+```bash
+# MacOSX
+source ~/.snapser/byows_env_setup.sh
+# Windows
+.\.snapser\byows_env_setup.ps1
 ```
 
-#### 3. byogs push
+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.
 
-Push your custom game server image.
+### BYO Game Server - Bring your own Game Server
+Snapctl commands for your custom game server
+
+#### 1. byogs help
+
+See all the supported commands
 
 ```bash
 # Help for the byogs command
-snapctl byogs push --help
-
-# Publish a new image
-# $image_tag = An image tag for your snap
-# Example:
-# snapctl byogs push byosnap-jinks-gs --tag my-first-image
-snapctl byogs push --tag $image_tag
+snapctl byogs --help
 ```
 
-#### 4. byogs publish
+#### 2. byogs publish
 
 Publish your custom game server image. This commend replaces the old way of creating, publishing image and
 then publishing the byogs. Now all you have to do is publish your image and create a fleet using the web portal.
@@ -511,7 +527,7 @@ snapctl byogs publish --tag $image_tag --path $code_root_path --resources-path $
 snapctl byogs publish --tag $image_tag --skip-build
 ```
 
-#### 5. byogs sync
+#### 3. byogs sync
 
 This command allows developers to rapidly build, update and push their BYOGs out to a Snapend fleet. Simply, make changes to your code locally, and then run this command to deploy your BYOGs straight to your Snapend fleet.
 
@@ -531,6 +547,38 @@ snapctl byogs sync --path /Users/DevName/Development/SnapserEngine/game_server -
 snapctl byosnap sync --path $code_root_path --tag $image_tag --snapend-id $snapend_id --fleet-names $fleet_names
 ```
 
+#### 4. byogs build
+
+Build your custom game server image.
+
+```bash
+# Help for the byogs command
+snapctl byogs build --help
+
+# Publish a new image
+# $image_tag = An image tag for your snap
+# $code_root_path = Local code path where your Dockerfile is present
+# Example:
+# snapctl byogs build byosnap-jinks-gs --tag my-first-image --path /Users/DevName/Development/SnapserEngine/game_server
+snapctl byogs build --tag $image_tag --path $code_root_path
+```
+
+#### 5. byogs push
+
+Push your custom game server image.
+
+```bash
+# Help for the byogs command
+snapctl byogs push --help
+
+# Publish a new image
+# $image_tag = An image tag for your snap
+# Example:
+# snapctl byogs push byosnap-jinks-gs --tag my-first-image
+snapctl byogs push --tag $image_tag
+```
+
+
 ### Game
 Snapctl commands for your game
 
@@ -543,36 +591,18 @@ See all the supported commands
 snapctl game --help
 ```
 
-#### 2. Create a game
+#### 2. game create
 Create a game
 ```bash
 snapctl game create --name $game_name
 ```
 
-#### 3. Enumerate games
+#### 3. game enumerate
 List all the games
 ```bash
 snapctl game enumerate
 ```
 
-### Generate
-Generator tool to help generate credentials
-
-#### 1. generate help
-See all the supported commands
-```bash
-# Help for the generate command
-snapctl generate --help
-```
-
-#### 2. Generate ECR Credentials
-Generate the ECR credentials. Game studios can use these credentials to self publish their images to Snapser.
-
-```bash
-snapctl generate credentials --category "ecr" --out-path $output_path
-
-```
-
 ### Snapend
 Snapctl commands for your snapend
 
@@ -585,7 +615,7 @@ See all the supported commands
 snapctl snapend --help
 ```
 
-#### 2. Snapend Downloads
+#### 2. snapend download
 
 Download Manifest, SDKs and Protos for your Snapend
 
@@ -619,7 +649,7 @@ 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. Clone Snapend
+#### 3. snapend clone
 
 Clone a Snapend from an existing manifest. Passing the blocking flag ensures your CLI command waits till the new Snapend is up.
 
@@ -638,10 +668,14 @@ snapctl snapend clone --game-id $game_id --name $snapend_name --env $env --manif
 snapctl snapend clone --game-id $game_id --name $snapend_name --env $env --manifest-path-filename "$path_to_manifest" --blocking
 ```
 
-#### 4. Apply Snapend Changes
+#### 4. 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.
+
+You can optionally pass a `--force` flag telling Snapser to ignore any diffs it may find in the current state of the Snapend and the one in the `applied_configuration` field of your manifest. Essentially, this flag allows you to stomp over any changes and tell Snapser to force apply.
+
+Separately, you can pass a blocking flag to make your CLI wait for the Snapend update to complete.
 
-Apply changes to your Snapend from a manifest. You should have the latest manifest before applying changes. This is to prevent
-a user stomping over someone elses changes. Passing the blocking flag ensures your CLI command waits till the update is complete.
 
 ```bash
 # Help for the apply command
@@ -649,13 +683,15 @@ snapctl snapend apply --help
 
 # Apply changes to a snapend via manifest
 # $path_to_manifest = Path to the manifest file; should include the file name
+# --force = Optional flag to tell Snapser that you do not want it to check the diff between the Snapend states and just force apply the changes
 # Example:
-# snapctl snapend apply --manifest-path-filename "C:\Users\name\Downloads\snapser-ox1bcyim-manifest.json" --blocking
+# snapctl snapend apply --manifest-path-filename "C:\Users\name\Downloads\snapser-ox1bcyim-manifest.json" --force --blocking
 snapctl snapend apply --manifest-path-filename "$path_to_manifest"
 snapctl snapend apply --manifest-path-filename "$path_to_manifest" --blocking
+snapctl snapend apply --manifest-path-filename "$path_to_manifest" --force --blocking
 ```
 
-#### 5. Update Snapend BYOSnap or BYOGs versions
+#### 5. snapend update
 
 Update your BYOSnap or BYOGs versions for the Snapend
 
@@ -675,7 +711,7 @@ snapctl snapend update --help
 snapctl snapend update --snapend-id $snapend_id --byosnaps $byosnaps --byogs $byogs --blocking
 ```
 
-#### 6. Get the Snapend state
+#### 6. snapend state
 
 Get the Snapend state
 
@@ -690,6 +726,25 @@ snapctl snapend state --help
 snapctl snapend state $snapend_id
 ```
 
+### Generate
+Generator tool to help generate credentials
+
+#### 1. generate help
+See all the supported commands
+```bash
+# Help for the generate command
+snapctl generate --help
+```
+
+#### 2. Generate ECR Credentials
+Generate the ECR credentials. Game studios can use these credentials to self publish their images to Snapser.
+
+```bash
+snapctl generate credentials --category "ecr" --out-path $output_path
+
+```
+
+
 ## Error codes
 ### CLI Return Codes
 | Error Code | Description                                              |
@@ -744,6 +799,7 @@ snapctl snapend state $snapend_id
 | 48         | BYOSNAP update version invalid version error             |
 | 49         | BYOSNAP publish error                                    |
 | 86         | BYOSNAP generate-profile                                 |
+| 87         | BYOSNAP swagger error                                    |
 
 
 ### Game Errors
@@ -777,6 +833,7 @@ snapctl snapend state $snapend_id
 | 73         | Snapend update server error                              |
 | 74         | Snapend update timeout error                             |
 | 75         | Snapend state error                                      |
+| 76         | Snapend manifest mismatch error                          |
 
 ### Generate Errors
 | Error Code | Description                                              |
@@ -784,3 +841,8 @@ snapctl snapend state $snapend_id
 | 80         | Generic generate error                                   |
 | 81         | Generate credentials error                               |
 
+### BYOWS Errors
+| Error Code | Description                                              |
+|------------|----------------------------------------------------------|
+| 95         | Generic byows error                                      |
+