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
| Property | Type | Description |
|---|---|---|
projectId | string | Required. The unique UUID of your project. Required for all build uploads. |
projectName | string | Display name of the project or mobile application. |
androidPath | string | Directory path where Android APK release builds are placed. Used by buildshare upload android. |
iosPath | string | Directory path where iOS IPA release builds are placed. Used by buildshare upload ios. |
defaultBranch | string | Default Git branch name associated with your project builds. |
Automatic File Discovery
When executing commands, the CLI automatically searches for a project configuration file in:
- The current working directory.
- Parent directories (traversing up the file hierarchy until the root).
The discovery order checks for any of the following filenames:
buildshare.jsonbuildshare.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.jsonGlobal Flags
These flags can be used across BuildShare CLI commands:
| Flag | Short | Description |
|---|---|---|
--version | -V, -v | Print 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 | -v | Enable detailed debug logging for request/response traces and network timing |
--help | -h | Print 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 versionWhen 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.
| Variable | Description |
|---|---|
BUILDSHARE_TOKEN | Personal 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 Code | Status | Meaning |
|---|---|---|
0 | Success | The command completed successfully with no errors. |
1 | General Error | Authentication failure, network timeout, invalid file format, or server error. |
2 | Misuse | Invalid 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