AlurKerja CLI

Panduan instalasi, konfigurasi profile/login, dan publish Addon ke platform AlurKerja menggunakan alurkerja-cli.

AlurKerja CLI (alurkerja-cli) adalah alat baris perintah resmi untuk men-scaffold, mem-package, dan publish Addon ke platform AlurKerja. Halaman ini adalah panduan urut dari nol — install, atur profile environment, login, hingga publish.

Konfigurasi CLI (profile, token, dst.) tersimpan di ~/.alurkerja/config.yaml.

Prasyarat

Node.js & npm — untuk menjalankan CLI dan membangun bundle views/ Addon.
Akses ke platform AlurKerja target — URL environment, SSO/Keycloak, realm, dan client-id. Minta ke admin bila belum punya.
Akun yang berhak mem-publish pada tenant tujuan.

1. Instal CLI

Ada dua cara — pilih salah satu.

A. Install global (rekomendasi)

npm install -g alurkerja-cli

# verifikasi
alurkerja --version
alurkerja --help

Perintah akan tersedia sebagai alurkerja ....

B. Tanpa install, via `npx`

npx alurkerja-cli --version

Sisa panduan ini memakai bentuk global alurkerja. Bila Anda memakai npx, ganti setiap alurkerja menjadi npx alurkerja-cli.

Memperbarui CLI

alurkerja update          # cek & update
alurkerja update --force  # paksa update

2. Tambahkan Connection Profile

Profile menyimpan detail koneksi sebuah environment (base URL platform, URL SSO, realm, client-id). Anda bisa punya banyak profile — misalnya production, staging, merapi.

alurkerja profile add <name> <url> <sso-url> <realm> <client-id>

Contoh (sesuaikan nilainya dengan environment Anda):

alurkerja profile add merapi \
  https://onprem.merapi.alurkerja.com \
  https://sso.merapi.alurkerja.com \
  internal \
  alurkerja-cli

Argumen	Keterangan
`name`	Nama bebas untuk profile (dipakai saat login & publish).
`url`	Base URL API platform.
`sso-url`	URL Keycloak/SSO untuk autentikasi.
`realm`	Realm Keycloak (mis. `internal`).
`client-id`	Client ID Keycloak (mis. `alurkerja-cli`).

Mengelola profile

alurkerja profile list           # daftar semua profile
alurkerja profile show <name>    # lihat detail profile
alurkerja profile edit <name>    # ubah profile
alurkerja profile remove <name>  # hapus profile

3. Set Profile Aktif

Profile aktif dipakai secara default oleh perintah login dan addon.

alurkerja profile use merapi    # alias: profile switch

# memakai profile aktif
alurkerja auth login

# atau sebut profile secara eksplisit
alurkerja auth login merapi

# bentuk singkat
alurkerja login merapi

Browser akan terbuka untuk proses login. Setelah berhasil, token tersimpan di ~/.alurkerja/config.yaml.

Fallback untuk environment headless

Bila callback browser tidak bisa dipakai (mis. server tanpa GUI), selesaikan dengan authorization code:

alurkerja auth token <authorization_code>

Cek & kelola sesi

alurkerja auth status   # cek status autentikasi
alurkerja auth logout   # keluar

5. Siapkan Addon

Mulai dari nol — scaffold template

Bila memulai Addon dari nol (tidak butuh autentikasi):

alurkerja addon init              # di folder saat ini
alurkerja addon init my-addon     # ke folder 'my-addon'

Template berisi struktur dasar: index.json, README.md, dan contoh action/view.

Sudah punya Addon — build bundle views

Bila Addon sudah ada, build frontend terlebih dahulu agar views/dist terisi/ter-update:

cd views
yarn install      # atau: npm install   (sekali di awal)
yarn build        # atau: npm run build  → output ke views/dist
cd ..

Perubahan yang hanya menyentuh index.json (mis. custom_views, actions, details) tidak perlu rebuild views/dist. Rebuild hanya wajib bila ada perubahan kode di views/src.

6. Publish Addon

Perintah publish mem-package folder Addon menjadi zip dan mengunggahnya. Wajib sudah login dan direktori harus memuat index.json yang valid.

# publish folder saat ini (memakai profile aktif)
alurkerja addon publish

# publish folder tertentu
alurkerja addon publish ./my-addon

# memakai profile tertentu tanpa mengubah profile aktif
alurkerja addon merapi publish

# 'push' adalah alias dari 'publish'
alurkerja addon push

Saat publish, CLI akan meminta tenant id secara interaktif:

📦 Publishing addon from . to profile: merapi (https://onprem.merapi.alurkerja.com)...
🔍 Validating addon structure...
✓ Addon key: bayu-addon
📦 Creating addon package...
✓ Package created (1.41 MB)
Masukan tenant id: <ketik tenant id Anda di sini>
📤 Uploading addon to server...
✓ ...

Karena ada prompt interaktif Masukan tenant id, jalankan perintah ini di terminal interaktif. Bila dijalankan lewat pipe/non-interaktif akan muncul error failed to read tenant id: EOF.

Verifikasi hasil publish

alurkerja addon list   # daftar addon yang sudah Anda publish

Troubleshooting

Gejala	Penyebab & Solusi
`failed to read tenant id: EOF`	Perintah dijalankan non-interaktif. Jalankan di terminal langsung lalu ketik tenant id.
`duplicate key value violates unique constraint "uni_plugins_name"`	Sudah ada plugin dengan `name` yang sama di server. Ubah `name` di `index.json` menjadi unik, lalu publish ulang. Kendala ini pada field `name`, bukan `addon_key`.
Error autentikasi / `401`	Token kedaluwarsa atau belum login. Jalankan `alurkerja auth status`, lalu `alurkerja auth login`.
`index.json` tidak valid	Validasi: `python3 -c "import json; json.load(open('index.json'))"`.
Komponen view tidak muncul setelah publish	Pastikan sudah `yarn build` dan komponen yang dirujuk di `custom_views` benar-benar di-`expose` di `views/webpack.config.js`.

Ringkasan Alur Cepat

# 1. Instal
npm install -g alurkerja-cli

# 2. Profile + aktifkan
alurkerja profile add merapi \
  https://onprem.merapi.alurkerja.com \
  https://sso.merapi.alurkerja.com \
  internal alurkerja-cli
alurkerja profile use merapi

# 3. Login
alurkerja auth login

# 4. Build views
cd views && yarn build && cd ..

# 5. Publish (ketik tenant id saat diminta)
alurkerja addon publish

# 6. Verifikasi
alurkerja addon list

Lihat Juga

Pembuatan Addon pada AlurKerja — anatomi index.json, struktur folder Addon, dan contoh action.
Custom Detail Task — membuat MFE custom untuk slot custom_views.DETAILS (tab Detail).

AlurKerja CLI

On this page