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
-
BYOSnap:
-
Generate: The ability to generate a base BYOSnap profile using the generate
command has
been deprecated. Instead its moved under byosnap
commands for consistency.
-
Snapend:
-
Input param --docker
for BYOGS and BYOSnap commands has been changed to --docker_filename
New Commands
- BYOSnap Generate Profile: You can now use a new command to generate a base BYOSnap profile.
snapctl byosnap generate-profile --out-path $outputPath --profile-filename $profileName
- BYOSnap Validate Profile: After you hand edit the base BYOSnap profile, you can use this
command to validate your BYOSnap profile before using it in other commands like
publish
and sync
snapctl byosnap validate-profile --path $path --profile-filename $profileName
snapctl byosnap validate-profile --resources-path $resources_path --profile-filename $profileName
- Release Notes: You can now view release notes for a specific version of Snapctl using the
release-notes
command.
snapctl release-notes releases
snapctl release-notes show
snapctl release-notes show --version $version
Requirements
Python 3.X and Pip
The Snapser CLI tool depends on Python 3.X and Pip. MacOS comes pre installed with Python. But
please make sure you are running Python 3.X. On Windows, you can download Python 3.X from the
Windows store.
Docker
Some of the commands also need docker. You can download the latest version of Docker from the
Docker website.
IMPORTANT: Open up Docker desktop and settings. Make sure this setting is disabled
Use containerd for pulling and storing images. This is because Snapser uses Docker
to build and push images to the Snapser registry. Having this setting enabled will
cause issues with the Snapser CLI tool.
Installation
Installing PIP on MacOS
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py
Installing PIP on Windows
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py
Once you have Python and Pip installed
pip install --user snapctl
If you also have Python 2.X on your machine, you may have to run the following command instead
pip3 install --user 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.
Upgrade
Upgrade your snapctl version
pip install --user snapctl --upgrade
Setup
Get your Snapser Access Key
Log in to your Snapser account. Click on your user icon on the top right and select, User Account.
In the left navigation click on Developer which will bring up your Personal API Key widget.
If you have not generated an API Key yet click on the Generate button to generate a new key.
You can generate up to 3 API Keys per user account.
IMPORTANT: Please make sure you save your API key in a safe place. You will not be able
to see it again.
Setup a local config
You have three ways to pass the API key to Snapctl
- Pass it via a command line argument with every command
- Pass it via an environment variable
- Pass it via a config file
Command line argument
Every Snapser command can take a command line argument --api-key <your_key>
. This will take precedence over
other methods.
Environment Variable
You can set an Environment variable SNAPSER_API_KEY=<your_key>
and then run your snapctl commands. This will
be evaluated after verifying if there is any command line argument.
Config file
Create a file named ~/.snapser/config
. Open it using the editor of your choice and replace with your
personal Snapser Access key. Save the file. Advantage of using this method is you can use the --profile
argument with your snapctl command to use different API keys. NOTE: You may want to pass your own path
instead on relying on the default one the CLI looks for. You can do so by setting an environment
variable SNAPSER_CONFIG_PATH='<your_custom_path>'
. Doing this will make sure that the CLI tool
will look for the config file at that path.
[default]
snapser_access_key = $your_api_key
Or you can run the following command
on MacOSX
# $your_api_key = Your Snapser developer key
echo -e "[default]\nSNAPSER_API_KEY=$your_api_key" > ~/.snapser/config
on Windows Powershell
# $your_api_key = Your Snapser developer key
echo "[default]
SNAPSER_API_KEY=$your_api_key" | Out-File -encoding utf8 ~\.snapser\config
Verify Snapctl installation
snapctl validate
Output will tell you if the Snapctl was able successfully validate your setup with the remote Snapser server
or not.
Advanced Setup
Snapser by default supports access to multiple accounts. You can create multiple profiles in your Snapser config
~/.snapser/config.
[profile personal]
snapser_access_key = <key>
[profile professional]
snapser_access_key = <key>
You can then set an environment variable telling Snapser which profile you want to use.
# Mac
export SNAPSER_PROFILE="my_profile_name";
# Windows
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.
Command variable name nomenclature
All commands follow these rules with their input variables
- A variable that is named
*path
= CLI tool expects a path to a folder - A variable that is named
*filename
= CLI tool expects the name of the file, without the path. - A variable that is named
*path_filename
= CLI tool expects the full path. The folder up to the name of the file.
Commands
Run the following to see the list of commands Snapser supports
snapctl --help
BYO Snap - Bring your own Snap
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.
snapctl byosnap --help
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
file at the root of your BYOSnap code and commit it to version control.
snapctl byosnap generate-profile --help
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
3. byosnap validate-profile
This command validates your BYOSnap profile.
snapctl byosnap validate-profile --help
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
4. byosnap publish
This command allows you to create and publish your BYOSnap. Running this command will first create a BYOSnap namespace on Snapser if not present. Then it will build and publish your code to your own
private ECR repo on Snapser. Finally it will assign a version to your BYOSnap so that you
can deploy it.
Requirements:
- This command needs docker.
- This command needs a BYOSnap profile. BYOSnap profile, holds information about
your BYOSnap like, name, description, etc and hardware requirements like CPU, Memory. We
recommend you store this file at the root of your BYOSnap and also add it to version control.
You can generate it using
snapctl generate profile --category byosnap --out-path $outputPath
.
snapctl byosnap publish --help
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_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
5. byosnap sync
This command is for development purposes. It allows developers to rapidly build, update and push their BYOSnap to a dev Snapend. Simply, make changes to your code locally, and then run this command to deploy your BYOSnap straight to your development Snapend.
Requirements:
- This command needs docker.
IMPORTANT: This command will only work for Dev Snapends. Additionally if the version you are using in this command happens to be used by a staging or a production snapend then sync
will not work. We do this to ensure that your staging and production BYOSnap images do not get impacted.
snapctl byosnap sync --help
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_id --path $code_root_path --version $version --snapend-id $snapend_id
6. byosnap create
Create a custom snap. Note that you will have to build, push and publish your snap image, for it to be useable
in a Snapend.
snapctl byosnap create --help
snapctl byosnap create --byosnap-id $byosnap_id --name "$name" --desc "$desc" --platform "$platform" --language "$language"
7. byosnap build
Build your snap image
snapctl byosnap build --help
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
8. byosnap push
Push your snap image to Snapser
snapctl byosnap push --help
snapctl byosnap push --byosnap-id $byosnap_id --tag $image_tag
9. byosnap upload-docs
Upload swagger.json and README.md for you Snap
snapctl byosnap upload-docs --help
snapctl byosnap upload-docs --byosnap-id $byosnap_id --tag $image_tag --resources-path $resources_path
10. byosnap publish-image
Publish a custom snap code image. This command executes, build
, push
and upload-docs
one
after the other.
IMPORTANT: Take note of the hardware architecture of machine and your Dockerfile commands.
Commands in docker file may be hardware architecture specific. Snapser throws a warning if it detects
a mismatch.
snapctl byosnap publish-image --help
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
11. byosnap publish-version
Publish a new version for your Snap. Only after your Snap version is published, you will be able
to use your snap in your Snapend. This command should be run after push
or publish-image
commands.
IMPORTANT: You need to have $byosnapProfile to run this command. BYOSnap profile is a JSON configuration
of your BYOSnap for the development, staging and production environments. You can generate a base version of this file using the snapctl generate profile --category byosnap --out-path <output_path>
command.
snapctl byosnap publish-version --help
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
See all the supported commands
snapctl byogs --help
2. byogs build
Build your custom game server image.
snapctl byogs build --help
snapctl byogs build --tag $image_tag --path $code_root_path
3. byogs push
Push your custom game server image.
snapctl byogs push --help
snapctl byogs push --tag $image_tag
4. 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.
IMPORTANT: Take note of the hardware architecture of machine and your Dockerfile commands.
Commands in docker file may be hardware architecture specific. Snapser throws a warning if it detects
a mismatch.
snapctl byogs publish --help
snapctl byogs publish --tag $image_tag --path $code_root_path
snapctl byogs publish --tag $image_tag --path $code_root_path --resources-path $resources_path
snapctl byogs publish --tag $image_tag --skip-build
5. 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.
snapctl byogs sync --help
snapctl byogs sync --path /Users/DevName/Development/SnapserEngine/game_server --tag my-first-image --snapend-id "jxmmfryo" --fleet-names "my-fleet,my-second-fleet"
snapctl byosnap sync --path $code_root_path --tag $image_tag --snapend-id $snapend_id --fleet-names $fleet_names
Game
Snapctl commands for your game
1. game help
See all the supported commands
snapctl game --help
2. Create a game
Create a game
snapctl game create --name $game_name
3. Enumerate games
List all the games
snapctl game enumerate
Generate
Generator tool to help generate credentials
1. generate help
See all the supported commands
snapctl generate --help
2. Generate ECR Credentials
Generate the ECR credentials. Game studios can use these credentials to self publish their images to Snapser.
snapctl generate credentials --category "ecr" --out-path $output_path
Snapend
Snapctl commands for your snapend
1. snapend help
See all the supported commands
snapctl snapend --help
2. Snapend Downloads
Download Manifest, SDKs and Protos for your Snapend
snapctl snapend download --help
snapctl snapend download --snapend-id $snapend_id --category $category --format $format --type $type --out-path $out_path
3. Clone Snapend
Clone a Snapend from an existing manifest. Passing the blocking flag ensures your CLI command waits till the new Snapend is up.
snapctl snapend clone --help
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
4. Apply Snapend Changes
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.
snapctl snapend apply --help
snapctl snapend apply --manifest-path-filename "$path_to_manifest"
snapctl snapend apply --manifest-path-filename "$path_to_manifest" --blocking
5. Update Snapend BYOSnap or BYOGs versions
Update your BYOSnap or BYOGs versions for the Snapend
snapctl snapend update --help
snapctl snapend update --snapend-id $snapend_id --byosnaps $byosnaps --byogs $byogs --blocking
6. Get the Snapend state
Get the Snapend state
snapctl snapend state --help
snapctl snapend state $snapend_id
Error codes
CLI Return Codes
Error Code | Description |
---|
0 | Operation completed successfully |
1 | General error |
2 | Input error |
3 | Resource not found |
Configuration Errors
Error Code | Description |
---|
10 | Configuration incorrect |
11 | Configuration error |
12 | Dependency missing |
BYOGS Errors
Error Code | Description |
---|
3 | BYOGs resource not found |
20 | Generic BYOGS error |
21 | BYOGS dependency missing |
22 | BYOGS ECR login error |
23 | BYOGS build error |
24 | BYOGS tag error |
25 | BYOGS publish error |
26 | BYOGS publish permission error |
27 | BYOGS publish duplicate tag error |
BYOSNAP Errors
Error Code | Description |
---|
3 | BYOSnap resource not found |
30 | Generic BYOSNAP error |
31 | BYOSNAP dependency missing |
32 | BYOSNAP ECR login error |
33 | BYOSNAP build error |
34 | BYOSNAP tag error |
35 | BYOSNAP publish image error |
36 | BYOSNAP publish image permission error |
37 | BYOSNAP publish image duplicate tag error |
38 | BYOSNAP create error |
39 | BYOSNAP create permission error |
40 | BYOSNAP create duplicate name error |
41 | BYOSNAP publish version error |
42 | BYOSNAP publish version permission error |
43 | BYOSNAP publish version duplicate version error |
44 | BYOSNAP publish version duplicate tag error |
45 | BYOSNAP update version error |
46 | BYOSNAP update version service in use |
47 | BYOSNAP update version tag error |
48 | BYOSNAP update version invalid version error |
49 | BYOSNAP publish error |
86 | BYOSNAP generate-profile |
Game 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 |
Snapend Errors
Error Code | Description |
---|
3 | Snapend resource not found |
60 | Generic snapend error |
61 | Snapend enumerate error |
62 | Snapend clone error |
63 | Snapend clone server error |
64 | Snapend clone timeout error |
65 | Snapend apply error |
66 | Snapend apply server error |
67 | Snapend apply timeout error |
68 | Snapend promote error |
69 | Snapend promote server error |
70 | Snapend promote timeout error |
71 | Snapend download error |
72 | Snapend update error |
73 | Snapend update server error |
74 | Snapend update timeout error |
75 | Snapend state error |
Generate Errors
Error Code | Description |
---|
80 | Generic generate error |
81 | Generate credentials error |