Omaship CLI

Install

RubyGems:

gem install omaship

Homebrew:

brew tap bloomedai/homebrew-tap
brew install omaship

Quick Start

omaship login --token <token>
omaship list
omaship use <ship-ref>
omaship info

Examples for SHIP_REF (from omaship list output):

omaship use acme.omaship.app
omaship use 17

Ship Selection

info resolves the target ship in this order:

  1. --ship <ship-ref>
  2. saved default from omaship use <ship-ref>
  3. if exactly one accessible ship exists: auto-select it and persist it as default
  4. otherwise: command fails and asks you to run omaship list + omaship use ...

Preferred ship reference format is the ship domain from omaship list. Numeric ids are also accepted.

Commands

  • omaship login --token <token>
  • omaship whoami
  • omaship list
  • omaship use <ship-ref>
  • omaship info [--ship <ship-ref>] (status and ship are aliases)
  • omaship new <name> (requires Full CLI access)
  • omaship complete <bash|zsh|fish> (print shell completion script)
  • omaship logout

Product Direction

Omaship CLI is evolving to support two complementary use cases:

  • standalone Omaship users launching and operating ship runs directly
  • Sokrates-orchestrated workflows where Sokrates calls Omaship capabilities

Related docs:

Local Development Run Execution

When you run omaship new <name> against local Omaship development (OMASHIP_HOST=http://localhost:3000), the initial run first installs gems from https://packages.omaship.com.

If that registry endpoint is unavailable, Omaship automatically retries bundle install through the local package proxy mirror at http://build.localhost:3000/packages.

Shell Completion

Homebrew installs completions automatically. For RubyGems installs, local repo usage, or other manual setups, install the generated script yourself:

Bash:

mkdir -p ~/.local/share/bash-completion/completions
omaship complete bash > ~/.local/share/bash-completion/completions/omaship

Zsh:

mkdir -p ~/.zfunc
omaship complete zsh > ~/.zfunc/_omaship

Then ensure ~/.zfunc is in fpath and reload completions:

autoload -Uz compinit
compinit

Fish:

mkdir -p ~/.config/fish/completions
omaship complete fish > ~/.config/fish/completions/omaship.fish

Environment

  • OMASHIP_HOST (default: https://omaship.com)
  • OMASHIP_TOKEN (optional alternative for login)

Credentials

  • Stored at ~/.config/omaship/credentials.json
  • File mode is 0600
  • Includes host, token, user, and optional default_ship

Local Development

Run from repository root:

mise exec ruby@4.0.2 -- env BUNDLE_GEMFILE=cli/Gemfile bundle exec ruby cli/bin/omaship -h

Run all CLI tests:

cd cli
mise exec ruby@4.0.2 -- bundle exec ruby -Itest -e 'Dir.glob("test/**/*_test.rb").sort.each { |f| require "./#{f}" }'

Release Automation

CLI releases are created by release-please (omaship/v* tags).

Required repository secrets:

  • RELEASE_PLEASE_PAT
  • HOMEBREW_TAP_GITHUB_TOKEN (must have push access to the tap repository)

Optional repository variable:

  • HOMEBREW_TAP_REPOSITORY (default: bloomedai/homebrew-tap)

RubyGems publish uses Trusted Publishing via GitHub OIDC.

Configure a trusted publisher for gem omaship:

  • repository owner: bloomedai
  • repository name: omaship
  • workflow filename: publish-gem.yml