Shiptavio CLI: submit a release from your terminal

1. Check the requirements

The CLI runs on Node.js and talks to the Shiptavio API. You need an account and an app record before you can submit.

• Node.js 20 or newer.
• A Shiptavio account.
• An app registered in the dashboard.
• Available release credits for the release you want to send.

2. Create a personal token

The CLI uses a personal token instead of your password. Create it in Account settings, copy it once, and treat it like a password.

• Open the dashboard and go to Account settings.
• Find Submit from your terminal.
• Name the token, create it, and copy the value.
• Revoke the token from the same page if it leaks.

3. Install and sign in

Install the CLI globally or run it with npx. Then sign in with the token. For a self-hosted instance, pass its base URL.

• The CLI stores the token in ~/.shiptavio/config.json with owner-only permissions.
• Set SHIPTAVIO_TOKEN in CI to skip the interactive login.

npm install -g shiptavio

npx shiptavio@latest help

shiptavio login

shiptavio login --api http://localhost:3000

4. Link the project folder

Run init inside the project. The CLI asks which app the folder belongs to and writes shiptavio.config.json.

• Commit shiptavio.config.json or add it to .gitignore. Either is fine.
• Run init once per project folder.
• If you have multiple apps, use a separate folder or config for each.

shiptavio init

5. Submit a release

The CLI asks for the version, shows the checklist, packages the source, and uploads it. Flags skip the prompts for scripts and CI.

• Use --ios or --android to target a platform. Defaults come from the app record.
• Use --build-command to tell our team exactly how to build the source.
• Use --notes for flavors, native setup, or a second config file.
• The source limit is 200 MB.

shiptavio submit

shiptavio submit --version 1.2.0 --ios --yes

shiptavio submit --version 1.2.0 --env-file .env.production

6. Check the release status

The CLI can show the release stage without opening the dashboard.

shiptavio status

shiptavio status --release <release-id>

7. Use the CLI in CI

Run init once in the repository, commit the config, and store the token as a CI secret. Then submit on a tag or a manual job.

• Do not echo the token in logs.
• Pin the CLI version if you need a reproducible pipeline.
• Add the build command and notes as flags or in the config.
• A CI job should not run init on every build if the config is committed.

SHIPTAVIO_TOKEN="$SHIPTAVIO_TOKEN" npx shiptavio@latest submit \
  --version "$VERSION" \
  --yes \
  --api https://shiptavio.com

8. Know what gets packaged

The CLI is designed to send source without common secrets. You should still check the file list before the first submission.

• In a git repo, it uses git ls-files --cached --others --exclude-standard.
• It always excludes .env and .env.* (except examples), *.pem, *.p12, *.pfx, *.key, *.keystore, *.jks, *.mobileprovision, *.cer, id_rsa, id_ed25519, .DS_Store, and Thumbs.db.
• It includes google-services.json and GoogleService-Info.plist when they exist because the build needs them.
• It never uploads a finished .ipa or .aab.

9. Troubleshooting

Most failures are authentication, app selection, or source size problems.

• That token is missing or was revoked: create a new token and run shiptavio login again.
• No apps yet: register an app at /dashboard/apps/new.
• This app has no release credits left: renew the subscription in the dashboard.
• Cannot reach the API: check --api and your network.
• Source too large: remove generated folders such as build output and dependency caches.