buildshare.in

Configuration & Flags

Reference for global flags, environment variables, and standard exit codes.

The BuildShare CLI behavior can be controlled using project configuration files, global flags, and environment variables, and respects standard exit codes for reliable automation.


Project Configuration

Project configuration files configure your project metadata and platform build paths so commands like buildshare upload android and buildshare upload ios work seamlessly without passing explicit file paths or flags.

Configuration Format

Project configuration uses strict camelCase properties. You can format the configuration as JSON or YAML:

{
  "projectId": "bfb72395-2527-42f8-8de8-5ec67e552510",
  "projectName": "Jobma Interview",
  "androidPath": "/path/to/android/app/build/outputs/apk/release",
  "iosPath": "/path/to/ios/builds",
  "defaultBranch": "bugs/flow"
}

Configuration Properties

PropertyTypeDescription
projectIdstringRequired. The unique UUID of your project. Required for all build uploads.
projectNamestringDisplay name of the project or mobile application.
androidPathstringDirectory path where Android APK release builds are placed. Used by buildshare upload android.
iosPathstringDirectory path where iOS IPA release builds are placed. Used by buildshare upload ios.
defaultBranchstringDefault Git branch name associated with your project builds.

Automatic File Discovery

When executing commands, the CLI automatically searches for a project configuration file in:

  1. The current working directory.
  2. Parent directories (traversing up the file hierarchy until the root).

The discovery order checks for any of the following filenames:

  • buildshare.json
  • buildshare.yaml
  • .buildshare.json
  • .buildshare.yaml

To override automatic discovery and supply a custom configuration file, pass -c or --config:

buildshare upload android -c ./custom/path/buildshare.json

Global Flags

These flags can be used across BuildShare CLI commands:

FlagShortDescription
--version-V, -vPrint the installed CLI version (BuildShare CLI <version>)
--json—Output results as structured JSON for scripting, piping, and automated workflows
--ci—Non-interactive CI mode — suppresses prompts, spinners, ANSI colors, and confirm dialogs
--verbose-vEnable detailed debug logging for request/response traces and network timing
--help-hPrint help information and flag descriptions for any command

Version Information

Checking the CLI version is supported via all standard flags and a dedicated subcommand:

# Standard version flag
buildshare --version

# Shorthand flags
buildshare -V
buildshare -v

# Detailed version subcommand (includes Commit, OS, Arch, and supports --json)
buildshare version

When passing --json to buildshare version, structured diagnostic output is returned:

{
  "version": "0.1.0",
  "commit": "9f1a23b",
  "buildDate": "2026-03-20T12:00:00Z",
  "os": "darwin",
  "arch": "arm64"
}

Environment Variables

Environment variables allow configuring authentication in headless CI/CD runners and containerized pipelines.

VariableDescription
BUILDSHARE_TOKENPersonal access token. Set this in CI environments to authenticate without interactive login.

Secret Management Best Practice

In GitHub Actions, store your token as a repository or organization secret (Settings → Secrets and variables → Actions) and pass it to the environment as ${{ secrets.BUILDSHARE_TOKEN }}. Never commit tokens directly to source control.


Exit Codes

The BuildShare CLI follows standard POSIX exit codes so CI/CD pipelines and shell scripts can automatically detect status and handle failures predictably:

Exit CodeStatusMeaning
0SuccessThe command completed successfully with no errors.
1General ErrorAuthentication failure, network timeout, invalid file format, or server error.
2MisuseInvalid command usage, unrecognized flag, or missing required arguments.

Shell Scripting Example

#!/usr/bin/env bash
buildshare upload ./app-release.apk --ci --json
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "Build uploaded successfully!"
elif [ $EXIT_CODE -eq 2 ]; then
  echo "Command syntax error. Check parameters."
  exit 1
else
  echo "Upload failed with error code $EXIT_CODE."
  exit 1
fi

On this page