Shipyard

Shipyard CLI

Alat untuk mengelola Ephemeral Environments di platform Shipyard.

Menggunakan asisten AI? CLI menyertakan server MCP: lihat Menggunakan Shipyard dari asisten AI.

Instalasi

• Linux dan macOS

  curl https://www.shipyard.sh/install.sh | bash
  

  Instalasi dilakukan ke /usr/local/bin, dan hanya menggunakan sudo jika tidak dapat menulis ke sana. Untuk menginstal di lokasi lain, seperti direktori yang Anda miliki, atur SHIPYARD_INSTALL_DIR:

  curl https://www.shipyard.sh/install.sh | SHIPYARD_INSTALL_DIR="$HOME/.local/bin" bash
  

• Windows Buka halaman rilis dan unduh executable untuk Windows.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

Memverifikasi unduhan

Setiap rilis menerbitkan checksums.txt yang berisi SHA-256 setiap binary. Skrip instalasi memeriksa binary terhadapnya dan menolak instalasi jika tidak cocok. Untuk memeriksa binary yang Anda unduh sendiri:

grep " shipyard-darwin-arm64$" checksums.txt | shasum -a 256 -c -

checksums.txt berasal dari rilis yang sama dengan binary, sehingga dapat mendeteksi unduhan yang rusak atau tidak lengkap, bukan rilis yang berkasnya telah diganti. Attestation di bawah ini adalah pemeriksaan bahwa binary dibuat oleh alur kerja rilis repo ini.

Dalam rilis setelah 1.9.0, setiap binary juga memiliki attestation provenance build bertanda tangan, yang menunjukkan alur kerja, commit, dan tag yang membuatnya, serta SBOM SPDX (shipyard-<os>-<arch>.sbom.json; .exe.sbom.json di Windows) yang mencantumkan bahan pembuatannya. Verifikasi attestation dengan GitHub CLI, dengan menyebutkan rilis yang Anda unduh (di sini v1.10.0):

gh attestation verify shipyard-darwin-arm64 -R shipyard/shipyard-cli \
  --signer-workflow shipyard/shipyard-cli/.github/workflows/release.yaml \
  --source-ref refs/tags/v1.10.0

Pertahankan --source-ref: tanpanya, pemeriksaan akan lolos untuk apa pun yang ditandatangani salinan alur kerja di cabang mana pun, bukan hanya build tag rilis tersebut.

Pemeriksaan ini menyebutkan tag, bukan commit-nya. Attestation untuk rilis yang ditarik tidak dihapus, jadi jika suatu versi dirilis lagi dengan tag yang sama, binary yang ditarik tersebut tetap lolos. Untuk mengunci commit juga, tambahkan --source-digest <commit SHA> dengan commit yang ditunjuk oleh tag tersebut.

Membangun ulang rilis

Rilis setelah 1.10.0 dapat direproduksi: membangun ulang tag rilis dengan versi Go dan GoReleaser yang sama akan menghasilkan binary yang identik byte demi byte di direktori mana pun. Versinya adalah GO_VERSION dan GORELEASER_VERSION dalam .github/workflows/release.yaml tag tersebut. Dengan GoReleaser itu terinstal, dan GO_VERSION sebagai pengganti 1.26.11 di bawah ini (GOTOOLCHAIN membuat Go menggunakan versi tersebut secara persis, mengunduhnya jika perlu, dan GOFLAGS= menghapus flag build Anda sendiri):

git clone https://github.com/shipyard/shipyard-cli && cd shipyard-cli
git checkout vX.Y.Z
GOTOOLCHAIN=go1.26.11 GOFLAGS= goreleaser release --clean --skip=publish,sbom
grep " shipyard-linux-amd64$" dist/checksums.txt

Digest-nya seharusnya cocok dengan baris yang sama di checksums.txt rilis tersebut. Jika tidak cocok, periksa versi Go dan GoReleaser Anda (GOTOOLCHAIN=go1.26.11 go version, goreleaser --version) sebelum mencurigai rilisnya. Alur kerja rilis memeriksa hal ini pada setiap commit rilis sebelum membangun rilis (scripts/check-reproducible.sh). SBOM tidak dapat direproduksi: SBOM mencatat waktu pembuatannya. Entri untuk modul CLI itu sendiri menampilkan versi (devel), karena build tidak menyertakan stempel VCS Go; shipyard --version mencetak versi rilis.

Memutakhirkan

shipyard upgrade

shipyard update melakukan hal yang sama. Perintah ini menginstal rilis terbaru dan menampilkan catatan rilisnya. Instalasi Homebrew dimutakhirkan dengan brew upgrade shipyard; instalasi lainnya mengunduh binary rilis, memverifikasinya terhadap checksums.txt rilis, lalu mengganti binary yang sedang berjalan. Jika binary tersebut berada di direktori yang tidak dapat Anda tulisi, seperti /usr/local/bin, jalankan sudo shipyard upgrade.

Tambahkan --prerelease untuk menyertakan pra-rilis, atau --force untuk menginstal ulang rilis saat ini (untuk instalasi Homebrew, gunakan brew reinstall shipyard sebagai gantinya).

Memutakhirkan dari 1.9.0 atau versi lebih lama

shipyard update di 1.9.0 dan versi lebih lama membandingkan versi sebagai teks, sehingga melaporkan 1.10.0 dan versi lebih baru sebagai lebih lama daripada versi yang Anda miliki. Lakukan pemutakhiran sekali dengan cara yang sama seperti saat Anda menginstal, dan shipyard upgrade akan berfungsi setelahnya:

• Linux dan macOS: curl https://www.shipyard.sh/install.sh | bash
• Windows: unduh executable dari halaman rilis
• Homebrew: brew upgrade shipyard

Pemberitahuan pembaruan

Saat rilis baru tersedia, CLI memberi tahu Anda setelah perintah selesai, paling banyak sekali sehari:

A new version of shipyard is available: 1.9.0 → 1.10.0
Run `shipyard upgrade` to install it. Release notes: https://github.com/shipyard/shipyard-cli/releases/tag/v1.10.0

CLI tidak pernah meminta apa pun atau menunggu masukan. Pemeriksaan berjalan di latar belakang saat perintah Anda berjalan; jika belum selesai saat perintah berakhir, CLI menunggu paling lama satu detik. Ini hanya terjadi saat CLI menghubungi GitHub, sekitar sekali sehari atau untuk mengambil catatan rilis yang terlewat. Proses pertama setelah pemutakhiran dengan cara lain, seperti brew upgrade, akan menampilkan catatan tersebut.

Pesan dikirim ke stderr, dan hanya jika stderr adalah terminal. Pesan tidak pernah ditampilkan di CI, di dalam agen coding AI yang mengidentifikasi dirinya (Claude Code, Codex, agen Cursor, Gemini CLI), atau untuk shipyard mcp serve. Untuk menonaktifkannya, atur SHIPYARD_NO_UPDATE_CHECK=1 atau tambahkan update_check: false ke ~/.shipyard/config.yaml.

Menonaktifkan pembaruan mandiri

Pada Shipyard yang di-host sendiri dan tidak dapat mengakses GitHub, CLI disertakan bersama rilis Shipyard Anda. Nonaktifkan pembaruan mandiri di sana dengan self_update: false di ~/.shipyard/config.yaml, atau SHIPYARD_SELF_UPDATE=false. CLI kemudian tidak akan pernah menghubungi GitHub: tidak ada pemberitahuan pembaruan, pemeriksaan latar belakang dari shipyard mcp serve, dan shipyard upgrade akan menolak dengan pesan bahwa pembaruan mandiri dinonaktifkan. update_check: false hanya menonaktifkan pemberitahuan dan pemeriksaan latar belakang.

Login

Jalankan shipyard login untuk menginisialisasi CLI. Anda akan diminta untuk login ke Shipyard melalui browser. CLI kemudian akan menyimpan token API Anda dalam konfigurasi lokal. Anda siap menjalankan perintah.

Shipyard yang di-host sendiri

Untuk menggunakan Shipyard yang di-host sendiri, arahkan CLI ke API-nya di ~/.shipyard/config.yaml (atau dengan SHIPYARD_API_URL) sebelum login:

api_url: https://shipyard.example.internal/api/v1
self_update: false

shipyard login kemudian membuka halaman login host tersebut, dan setiap perintah memanggil API itu. Atur self_update: false jika instalasi tidak dapat mengakses GitHub (lihat Menonaktifkan pembaruan mandiri).

Jika Anda sudah login ke Shipyard lain (seperti shipyard.build), shipyard login akan mempertahankan token tersebut dan menyatakan bahwa Anda sudah login. Hapus api_token dari berkas konfigurasi (dan hapus pengaturan SHIPYARD_API_TOKEN) sebelum login ke instalasi yang di-host sendiri.

Atau Atur Token Anda Secara Manual

Atur token API Shipyard Anda sebagai nilai variabel lingkungan SHIPYARD_API_TOKEN.

Anda bisa mendapatkannya dengan membuka halaman profil Anda.

Hubungi kami di support@shipyard.build jika Anda ingin mengaktifkan akses API untuk org Anda. Jika ada pertanyaan lain, silakan bergabung dengan komunitas kami di Slack.

shipyard set token

Sebagai alternatif, Anda dapat menggunakan berkas konfigurasi yang secara default disimpan di $HOME/.shipyard/config.yaml. Saat pertama kali menjalankan CLI, CLI akan membuat konfigurasi kosong default yang kemudian dapat Anda edit.

Anda juga dapat menentukan jalur konfigurasi non-default dengan menambahkan flag --config {path} ke perintah apa pun.

Tambahkan nilai konfigurasi apa pun ke konfigurasi Anda dan pastikan berkas mengikuti sintaks YAML. Contohnya:

api_token: <your-token>
org: <your-non-default-org>

Nilai variabel lingkungan akan menggantikan nilai terkait di konfigurasi.

Penggunaan dasar

Mendapatkan semua org tempat Anda menjadi anggota

shipyard get orgs

Mengatur org default global

shipyard set org {org-name}

Mendapatkan org yang saat ini dikonfigurasi

shipyard get org

Mencantumkan semua environment

shipyard get environments

Flag yang tersedia:

Nama	Deskripsi	Tipe	Nilai Default
branch	Memfilter berdasarkan nama branch	string
deleted	Mengembalikan environment yang dihapus	boolean	false
json	Mencetak output JSON lengkap	boolean	false
name	Memfilter berdasarkan nama aplikasi	string
org-name	Memfilter berdasarkan nama org, jika Anda tergabung di beberapa org	string	org default Anda
page	Nomor halaman yang diminta	int	1
page-size	Ukuran halaman yang diminta	int	20
pull-request-number	Memfilter berdasarkan nomor pull request	string
repo-name	Memfilter berdasarkan nama repo	string

Contoh:

• Mencantumkan semua environment yang menjalankan repo flask-backend pada branch main:

shipyard get environments --repo-name flask-backend --branch main

• Mencantumkan semua environment yang dihapus:

shipyard get environments --deleted

Mendapatkan detail environment tertentu berdasarkan UUID-nya

shipyard get environment {environment_uuid}

Flag yang tersedia:

Nama	Deskripsi	Tipe	Nilai Default
json	Mencetak output JSON lengkap	boolean	false
org	Org environment, jika Anda tergabung di beberapa org	string	org default Anda
bypass-token	Hanya mencetak token bypass environment, untuk skrip	boolean	false

--bypass-token memungkinkan skrip menggunakan token tanpa ada yang mengetik atau mencetaknya:

SHIPYARD_TOKEN=$(shipyard get environment {environment_uuid} --bypass-token) && \
  export SHIPYARD_TOKEN && curl -b "shipyard_token=$SHIPYARD_TOKEN" https://your-environment-url/

Menghentikan environment yang sedang berjalan

shipyard stop environment {environment_uuid}

Memulai ulang environment yang dihentikan

shipyard restart environment {environment_uuid}

Membatalkan build yang sedang berlangsung untuk sebuah environment

shipyard cancel environment {environment_uuid}

Membangun ulang environment

shipyard rebuild environment {environment_uuid}

Mengaktifkan kembali environment yang dihapus

shipyard revive environment {environment_uuid}

Men-deploy environment terpisah

Buat environment baru yang independen ("terpisah") dengan mengkloning build aplikasi yang sudah ada. Fitur environment terpisah harus diaktifkan untuk org Anda.

shipyard detached deploy {application_build_uuid} --name my-detached-env

Ganti branch per repo dan tentukan apakah environment terpisah dibangun ulang saat ada commit baru:

# Override the branch for a repo, and never rebuild on new commits
shipyard detached deploy {application_build_uuid} --name my-detached-env --branch web=feature-x --build-on-commit never

# Per-repo build-on-commit settings (always | inherit | never)
shipyard detached deploy {application_build_uuid} --build-on-commit-for web=always --build-on-commit-for api=never

Menghapus environment terpisah

Berikan UUID environment, atau UUID salah satu build aplikasinya (yang ada di URL halaman detail build). Cara ini hanya dapat digunakan untuk menghapus environment terpisah; environment dasar, pull request, atau remote akan ditolak. Menghapus environment yang sudah dihapus akan tetap berhasil.

shipyard detached delete {environment_uuid}
shipyard detached delete {application_build_uuid}

Mendapatkan semua layanan dan port yang diekspos untuk sebuah environment

shipyard get services --env {environment_uuid}

Menjalankan perintah di layanan environment yang sedang berjalan

Jalankan perintah apa pun dengan argumen dan flag apa pun di layanan tertentu untuk environment yang sedang berjalan. Berikan argumen perintah setelah garis miring ganda. Sesi ini mencegah environment dihentikan karena idle hanya selama Anda mengetik di dalamnya, hingga 12 jam.

shipyard exec --env {environment_uuid} --service {service_name} -- bash

Meneruskan port layanan environment yang sedang berjalan

shipyard port-forward --env {environment_uuid} --service {service_name} --ports {local_port}:{service_container_port}

port-forward atau logs --follow yang terbuka mencegah environment dihentikan karena idle hingga 12 jam.

Mendapatkan log layanan environment yang sedang berjalan

shipyard logs --env {environment_uuid} --service {service_name}

Mengunjungi environment

shipyard visit {environment_uuid}

Flag yang tersedia:

Nama	Deskripsi	Tipe	Nilai Default
follow	Mengikuti output log	boolean	false
tail	Jumlah baris log terbaru yang ditampilkan	int	3000

Bekerja dengan volume

Mencantumkan semua volume dalam sebuah environment

shipyard get volumes --env {environment_uuid}

Mencantumkan semua snapshot volume dalam sebuah environment

shipyard get snapshots --env {environment_uuid}

Mereset volume dalam sebuah environment

shipyard reset volume --env {environment_uuid}

Membuat snapshot dalam sebuah environment

shipyard create snapshot --env {environment_uuid}

Memuat snapshot volume dalam sebuah environment

shipyard load snapshot --env {environment_uuid} --sequence-number {n}

Mengunggah file ke volume dalam sebuah environment

shipyard upload volume --env {environment_uuid} --volume {volume} --file {filepath.bz2}

Memanggil REST API secara langsung

shipyard api /api/v1/environment
shipyard api -X PUT /api/v1/environment/{environment_uuid}/env-vars --input body.json

Jalur harus dimulai dengan /api/v1 atau /api/v2; token dan org Anda akan ditambahkan secara otomatis. bypass_token dan kredensial kubeconfig akan disamarkan kecuali Anda memberikan --include-secrets.

Menghubungkan ke telepresence

shipyard telepresence connect --env {environment_uuid}

Dari sana, Anda akan dapat berkomunikasi langsung dengan semua pod di namespace. Anda mungkin perlu menggunakan hostname namespace untuk berkomunikasi dengan layanan, yang bisa Anda dapatkan melalui telepresence status di bagian Namespace. Misalnya, untuk berkomunikasi dengan redis, Anda akan menggunakan redis.shipyard-app-build-{uuid}

Build executable dari kode:

Anda dapat membuat executable dengan menjalankan perintah berikut:

make

Untuk menjalankan executable baru ini:

./shipyard

Aktifkan Autocompletion

Bash

Skrip ini bergantung pada paket bash-completion. Jika belum terinstal, Anda dapat menginstalnya melalui pengelola paket OS Anda. Untuk memuat completions di sesi shell saat ini:

source <(shipyard completion bash)

Untuk memuat completions di setiap sesi baru, jalankan perintah berikut satu kali.

Di Linux:

shipyard completion bash > /etc/bash_completion.d/shipyard

Di macOS:

shipyard completion bash > $(brew --prefix)/etc/bash_completion.d/shipyard

Zsh

Jika shell completion belum diaktifkan di lingkungan Anda, Anda perlu mengaktifkannya. Anda dapat menjalankan perintah berikut satu kali:

echo "autoload -U compinit; compinit" >> ~/.zshrc

Untuk memuat completions di sesi shell saat ini:

source <(shipyard completion zsh); compdef _shipyard shipyard

Untuk memuat completions di setiap sesi baru, jalankan perintah berikut satu kali.

Di Linux:

shipyard completion zsh > "${fpath[1]}/_shipyard"

Di macOS:

shipyard completion zsh > $(brew --prefix)/share/zsh/site-functions/_shipyard

Anda perlu memulai shell baru agar pengaturan ini berlaku.

Fish

Untuk memuat completions di sesi shell saat ini:

$ shipyard completion fish | source

Untuk memuat completions di setiap sesi, jalankan perintah berikut satu kali:

shipyard completion fish > ~/.config/fish/completions/shipyard.fish

PowerShell

Untuk memuat completions di sesi shell saat ini:

shipyard completion powershell | Out-String | Invoke-Expression

Untuk memuat completions di setiap sesi baru, jalankan:

shipyard completion powershell > shipyard.ps1

dan muat file ini dari profil PowerShell Anda.

Gunakan Shipyard dari asisten AI (MCP)

shipyard mcp serve menjalankan server Model Context Protocol, sehingga asisten seperti Claude Code, Claude Desktop, Cursor, atau Codex dapat mencantumkan, memeriksa, membangun ulang, dan mengonfigurasi lingkungan Anda, membaca log layanan, mengelola volume, serta memverifikasi perubahan yang didorong terhadap lingkungannya.

Setelah CLI masuk, tambahkan ke Claude Code:

claude mcp add shipyard -- shipyard mcp serve

Lalu ajukan pertanyaan seperti:

• "Lingkungan apa saja yang sedang berjalan untuk repo web?"
• "Tampilkan log layanan api di lingkungan branch saya."
• "Mengapa build terbaru lingkungan ini gagal?"
• "Atur FEATURE_FLAGS=beta di lingkungan ini dan mulai ulang layanan worker."
• "Saya baru saja melakukan push. Verifikasi perubahan tersebut terhadap lingkungannya." (atau /mcp__shipyard__verify)

Lihat panduan MCP untuk mengetahui cara menyiapkannya di klien lain, konfigurasi, daftar lengkap alat, prompt verify, dan pemecahan masalah.