youappz/cli

The @youappz/cli is a way to interact with the Youappz platform via the command line and the only way to deploy new versions. You can run it from your local machine, or from a build script in a continuous deployment workflow.

Installation

The CLI is installed via npm/yarn:

If you have docker installed, you can create an alias that will run the docker image:

yarn global add @youappz/cli
export PATH="$PATH:$(yarn global bin)"

npm install @youappz/cli -g

touch ~/.appz.yml alias appz='docker run --rm -it --volume "$PWD:/app/src" --volume "$HOME/.appz.yml:/home/appz/.appz.yml" -e WWWUSER=$UID --name appz youappz/cli appz'

Usage

Once installed, the command appz should be globally available on your system. Running appz help will display a list of all the available commands:

appz [command] [options] Commands: account Display a summary of the current Youappz account. apikey Get the api key for the current Youappz account. create Create a new Youappz website in the current directory delete Delete the current website deploy Deploy the website in the current directory. domain Register a custom domain for the current website info Display a summary of the current website login Login to your Youappz account list list of all websites versions Manage website versions Type appz help COMMAND for more details

Behind a proxy

The CLI will honor the HTTPS_PROXY environment variable when making outbound network calls.

Commands

account

Display a summary of the current Youappz account including the list of websites.

appz account

apikey

Get the api key for the current Youappz account. This value should be set as the APPZ_API_KEY environment variable in a CI service. Read about setting up a CI environment. Run with the --reset arg to reset to a new value.

Options

-R, --reset

Reset the account api key to a new value.

Examples

appz account
appz account --reset

create

Create a new Youappz website in the current directory. If no appz.yml file exists in the current directory, a new one will created. If there is already an appz.yml file, then the "id" property will overriden with the new website's unique identifier.

Options

-n, --name

The desired name of the website. Names are globally unique and must be URL friendly (lower-case letters, numbers, and dashes). If no name is specified then a random website name will be generated for you. You can always use the rename command to change the name later.

-q, --quick-start

The name of a quick start from the Youappz Quick Start gallery to use to kickstart the website. Quick starts are available for Hugo, Jekyll, and vanilla HTML5.

-S, --source

URL to a .tar.gz archive to create the new website from. This will automatically create a new directory.

Examples

appz create # Creates website at the current directory
appz create -n website-name
appz create --quick-start hugo/agency
appz create --source https://html5up.net/editorial/download --name html5up-demo
appz create -S https://github.com/BlackrockDigital/startbootstrap-business-casual/archive/gh-pages.tar.gz

delete

Delete the website at the current directory. This will take down the website resulting in a 404 page. If the site is subscribed to the Pro plan, recurring payments will stop. You will be prompted to confirm the name of the website.

appz delete

deploy

Deploy a new version of the website in the current directory.

Options

-d, --directory

Specify the sub-directory where the built website assets are located. This overrides any value specified in the deploy section of the appz.yml file. If no value is specified in either location the current directory is deployed.

-s, --stage

Specify the deploy stage for the deployment. This impacts the URL of the deployed version. For example passing --stage test will make the new version available at https://www--test.customdomain.com or https://SITENAME--test.sitez.live. If no value is provided then the deployment will target the production URL.

-m, --message

A short message that you want to attach to the deployment metadata. If being invoked from a CI server, it may be useful to pass the git commit message and the URL to the commit details that triggered the build. This information will be displayed in the Youappz control panel as part of the deployment history. It will also be displayed in any email or Slack deploy alerts.

-c, --commit-url

The URL to the commit that triggered this deployment. Also mostly useful when being invoked by a CI server. This URL will be linkable from the Youappz control panel.

If you want to avoid certain files from getting deployed with your site, you can specify an ignore property in the deploy section of your appz.yml. See the configuration section for details.

Examples

appz deploy
appz deploy --directory _site
appz deploy --stage test
appz deploy --message "Commit message" --commit-url https://github.com/owner/repo/commit/2495349f

domain

Register a custom domain for the current website. This command requires that your website has already been upgraded to the Pro plan. If you want to run your website at the apex domain, i.e. https://mydomain.com, your DNS provider needs to support ANAME or ALIAS records. For details see the apex domains docs.

Options

-n, --name

The name of the domain (without any sub-domain, i.e. mydomain.com)

-N, --subdomain

The subdomain you want your website to be accessible at. For apex domain enter the value '@'.

You can also run the command without any arguments to get status information on the domain as well as DNS details.

appz domain --name mydomain.com --subdomain www
appz domain --name mydomain.com --subdomain @
appz domain

info

Display summary information about the current website.

appz info

login

Login to your Youappz account. You'll be prompted to enter your email and password. If your credentials are correct, a file is written at ~/.app.yml with an auth token that is passed in subsequent commands. The token is valid for 24 hours after which you'll be prompted to login again.

appz login

versions

Manage website versions including displaying all versions, deleting versions, pushing a version to a deploy stage, and deleting a deploy stage. Which action is carried out depends on the combination of options provided.

Options

-n, --name

The name of the version (i.e "v21") or version number "21" of the version to act on.

-D, --delete

Delete the version identified by the --name option.

-s, --stage

If specified in conjunction with the --name option, indicates the stage to push the version to. If used in conjunction with the --delete option, then this specifies the stage to delete.

Examples

appz versions # Display a list of all versions
appz versions -D --name v21 # Delete version v21
appz versions --name v2 --stage production # Deploy version v2 to production stage
appz versions -n v3 -s test # Deploy version v3 to test stage
appz versions --delete --stage test # Delete the test deploy stage