Building videos using the Narakeet Command-line Tool

The Narakeet command line tool (CLI) is the easiest way to automate video build projects from a command line, or integrate Narakeet into custom build tools. This page explains how you can use the Narakeet CLI to quickly build videos.

Installing and setting up the Narakeet CLI

For general information on installing and setting up the Narakeet command line tool, check out Using the Narakeet Command-line Tool.

Creating videos using Narakeet CLI

The Narakeet command-line tool has 4 supported workflows for video builds. Choose a workflow using the --repository-type argument:

  • Build from files in a local disk directory (--repository-type local-dir)
  • Build from a local zip archive (--repository-type local-zip)
  • Build from a remote zip archive, uploaded to a publicly accessible URL (--repository-type zip-url)
  • Build from a GitHub repository (--repository-type github)

You can find more about each option below:

Building from files in a local directory

NOTE: This option will automatically create an archive from all the files in a specified directory, and upload it to Narakeet. It requires your OS temporary directory to be writable. If the temporary dir is not writable, use the local-zip repository type instead.

To create a video from files on a local disk, put the script and all the referenced assets into a directory, and execute the client tool using the following arguments:

  • set the --repository-type to local-dir (all lowercase).
  • set the directory containing the files using the --repository argument
  • set the path inside the directory for your main script file using the --source argument.
  • provide the API key as --api-key

For example, the following command will create a video from the my-video-project directory, with the main video script in video.txt inside that directory.

narakeet-api-client \
  --repository-type local-dir \
  --repository my-video-project \
  --source video.txt \
  --api-key $API_KEY

By default, the resulting video is downloaded as result.mp4 in the current directory. You can set a different path for the result using --output. For example, this command will save the result in /tmp/video.mp4.

narakeet-api-client \
  --repository-type local-dir \
  --repository my-video-project \
  --source video.txt \
  --output /tmp/video.mp4 \
  --api-key $API_KEY

Building from a local ZIP archive

If you do not want the command-line client to package your project automatically (for example, if you are using symbolic links, or if the directory contains security-sensitive credentials that you do not want to upload to Narakeet), you can package the project as a ZIP file yourself, and then trigger the build with the following arguments:

  • set the --repository-type to local-zip (all lowercase)
  • set the path to the zip archive using --repository
  • set the path inside the archive four main script file using --source

For example, the following command will create a video from assets packaged inside my-video.zip, containing the main script file as script.txt.

narakeet-api-client \
  --repository-type local-zip \
  --repository my-video.zip \
  --source script.txt \
  --api-key $API_KEY

By default, the resulting video is downloaded as result.mp4 in the current directory. You can set a different path for the result using --output. For example, this command will save the result in /tmp/video.mp4.

narakeet-api-client \
  --repository-type local-zip \
  --repository my-video.zip \
  --source script.txt \
  --output /tmp/video.mp4 \
  --api-key $API_KEY

Building from a remote ZIP archive

You can also trigger a build from a remote zip archive, for example if you are running a build process in a cloud environment, and the project artifacts are available on a public URL. This can help you speed up the build by avoiding data transfers from a local machine. A common use-case for this would be to create a pre-signed URL using AWS S3, and provide that to Narakeet as the repository source.

Package your project as a ZIP file, and upload it somewhere for Narakeet to download. Then trigger the build with the following arguments:

  • set the --repository-type to zip-url (all lowercase)
  • set the URL for your zip archive using --repository (this must be publicly accessible from AWS, where Narakeet API is hosted)
  • set the path inside the archive four main script file using --source

For example, the following command creates a video from an archive hosted at https://example.com/video-projects/v1.zip, using the script file contained as script.txt inside the archive. It will save the video to out.mp4.

narakeet-api-client \
  --repository-type zip-url \
  --repository https://example.com/video-projects/v1.zip \
  --source script.txt \
  --output out.mp4 \
  --api-key $API_KEY

Building from files on GitHub

The easiest way to build videos from projects on GitHub is to use the Narakeet GitHub action page. See our page Building videos using GitHub actions for more information. For more flexibility, you can also trigger the build from video assets stored to GitHub using the command line client. Provide the following options:

NOTE: You will need a GitHub access token to trigger GitHub builds manuallu. To obtain a token from GitHub, see Creating a personal access token.

  • set the --repository-type to github (all lower-case)
  • set the --repository to your GitHub repository name (user/project)
  • set the path inside the repository to the main script using --source
  • set the GitHub access token using --github-token. Note that this token must have read access to the repository.
  • optionally set the commit SHA using the --github-sha argument (see Building from a specific branch or commit reference below)

For example, the following command will run the build from the narakeet/examples GitHub repository, using the main source script from hello-world/script/source.md and save the result to out.mp4.

narakeet-api-client \
  --source hello-world/script/source.md \
  --repository narakeet/examples \
  --repository-type github \
  --github-token $GITHUB_TOKEN \
  --output out.mp4 \
  --api-key $API_KEY

Building from a specific branch or commit reference

By default, the command-line tool will request a build from the head commit in the main branch of your repository. To build from a specific branch or commit reference, provide the SHA hash of the commit using the --github-sha argument. For example, the following command will run the build from the 588567e7587f3cb5d431ff9246b96eddfa76b265 SHA, and save the result to out.mp4.

narakeet-api-client \
  --source hello-world/script/source.md \
  --repository narakeet/examples \
  --repository-type github \
  --github-token $GITHUB_TOKEN \
  --github-sha 588567e7587f3cb5d431ff9246b96eddfa76b265 \
  --output out.mp4 \
  --api-key $API_KEY

More information