Uku CLI

Selle artikli lõpuks tead, milleks käsurida on ja kuidas seda paigaldada. Tead ka, mida see oskab, kuidas see sinu API võtit hoiab ja kuidas see kirjutamisi käsitleb.

Uku CLI on inimestele ja programmidele, kes juba terminalis töötavad. Näiteks arendajale, kes skriptib muudatuse üle paljude kirjete, CI-tööle ja koodiagentidele nagu Claude Code või Cursor, kes Ukut kellegi eest kasutavad.

See ei ole õige pind mittetehnilisele töötajale. Inimene, kes tahab küsida küsimuse tavakeeles, peaks kasutama AI-assistenti. Assistent ei vaja midagi paigaldatavat ega oma mandaati tema masinas.

CLI eelis assistendi ees on ökonoomsus. Kuna käsk on üks tekstirida, saab agent mitu toimingut ühte sammu aheldada, selle asemel et kulutada igale eraldi päring. Kui töö on muudatuste nimekiri, mitte üks küsimus, ongi see erinevus põhjus käsurea järele haarata.

Uku CLI on üks iseseisev programm. Sellega kõrvale ei pea paigaldama ühtegi käituskeskkonda, pakipuud ega interpretaatorit. See on üks fail, mille paned kuhugi oma PATH-i.

macOS-il ja Linuxil paigaldab selle üks käsk:

curl -fsSL https://getuku.com/install-cli | sh

Kulub paar sekundit ja sinult ei küsita midagi peale kolme tavalise tööriista — curl, openssl ja kontrollsumma tööriist. Paigaldaja keeldub käivitumast, kui neist mõni puudub, selle asemel et mõni kontroll vahele jätta. Järjekorras teeb käsk nii:

1. Leiab uusima väljalaske ja arvutab välja, milline ehitus sinu masinale sobib: macOS või Linux, Intel või Apple’i räni ja ARM.
2. Laeb alla selle väljalaske sõrmejälgede nimekirja koos allkirjaga, mis tõendab, et selle avaldas Uku. Allkirja kontrollib ta paigaldajasse endasse sisse ehitatud võtme vastu.
3. Laeb alla ainsa sinu masinale mõeldud programmi ja kontrollib selle sõrmejälge allkirjastatud nimekirja vastu.
4. Paigaldab selle kausta sinu PATH-is, lisab kausta PATH-i, kui seda seal ei ole, ja hoiatab, kui shelli alias nimega uku selle varjaks.
5. Pakub sind sisse logida ja su koodiagendid ühendada, kui oled terminali taga. Ütle ei ja rohkem midagi ei juhtu.

Kui mõni neist kontrollidest läbi kukub, ei paigaldata mitte midagi. Mitte osalist paigaldust ega hoiatust, millest saab mööda klõpsata: käsk peatub ja ütleb, mis läbi kukkus. Puuduv allkiri loeb läbi kukkunud allkirjaks.

Kontrolli käsuga uku --version ja pärast sisselogimist käsuga uku doctor.

Windowsi jaoks ühe rea paigaldajat ei ole ja skript ütleb seda otse, selle asemel et pooleldi töötada. Laadi see käsitsi alla. Ava projekti väljalasete leht ja võta uusim windows-amd64 fail koos selle kõrval olevate failidega SHA256SUMS, SHA256SUMS.sig ja release-pubkey.pem. Kontrolli, et faili sõrmejälg ühtib SHA256SUMS faili vastava reaga. Kui sul on openssl (Git for Windows ja WSL sisaldavad seda), kontrolli ka SHA256SUMS faili allkirja avaliku võtme vastu. See kontroll tõestab, et nimekiri on tõesti Uku oma — ühe rea paigaldaja teeb mõlemad kontrollid sinu eest automaatselt. Ilma openssl-ita oled kontrollinud ainult terviklust. Seejärel nimeta fail ümber uku.exe failiks ja pane kausta, mis on sinu PATH-is. Täpsed käsud on projekti README failis.

Ise ehitamine on alati võimalik ja see on vastus platvormile, mida avaldatud ehitused ei kata. Klooni projekt, käivita selle ehitusskript ja kopeeri valminud programm oma PATH-i. Ehitamiseks on vaja Go 1.26.8 või uuemat ja mitte midagi muud: eraldi ehitustööriista ega koodi genereerimise sammu ei ole.

uku update uuendab selle kohapeal. Käsk tõmbab sama allkirjastatud paigaldaja, kontrollib allkirja ja käivitab selle, nii et uuendus läbib täpselt need kontrollid, mis värske paigalduski.

Iseenesest ei uuene midagi. Ülimalt kord päevas, tavalise käsu käigus, kontrollib CLI, kas uuem versioon on olemas, ja trükib ühe rea, kui on. Sellega ta piirdub: midagi ei laadita alla ega paigaldata enne, kui käivitad ise uku update.

Uku CLI sisselogimine on üks käsk, uku auth login. See käsk küsib kaks väärtust, mida iga API v3 päring vajab: sinu Ettevõtte UUID ja API võtme. Käsk kontrollib need API vastu enne, kui midagi kettale kirjutab. Nii kukub valesti trükitud võti läbi juba viiba juures, mitte esimese päris käsu peal.

Kes seda teha saab. Ettevõtte omanikud ja Ettevõtte peakasutajad Elite paketis saavad luua võtme, millega CLI sisse logib. Edasi saab seda kasutada igaüks, kelle käes võti on.

Tee: Seaded & Äpid → Avalik API → Avalik API

Võtme loomine on täies mahus kirjeldatud artiklis Avalik API v3. CLI kasutab tavalist v3 võtit ega lisa omaenda mandaati.

Pärast sisselogimist hoitakse mandaati failis sinu kodukataloogis, mida saab lugeda ainult sinu enda kasutajakonto. Faili parsitakse, mitte kunagi ei käivitata: rikutud või muudetud profiili koheldakse andmetena, nii et miski selles ei saa sinuna käsuna joosta.

Võtit saab hoida ka oma operatsioonisüsteemi mandaadihoidlas — macOS-i Keychainis või Linuxi Secret Service’is. See on väljas, kuni sa selle sisse lülitad. Tasub täpselt öelda, mida see annab. Võti ei ole siis failis, mille CLI kirjutas, nii et varukoopia või sünkroonitud dotfiles-kaust seda kaasa ei kanna. Millegi eest, mis juba sinuna töötab, see võtit ei peida.

Kui sul on Ukus mitu ettevõtet, hoiab CLI iga ettevõtte kohta ühte profiili sinu valitud nime all. Nende vahel vahetad ühe käsu lipuga või tehes ühe neist aktiivseks. Soovitatav harjumus on hoida päris ettevõtte kõrval liivakastiettevõtet: harjuta muudatust seal ja käivita seejärel sama käsk büroo peal.

Kõik, mida CLI teeb, on all avalik API, nii et vastus küsimusele „kas see oskab X-i” on enamasti jah. Peale selle annab CLI igapäevase töö kujul, mida inimene või agent saab käivitada ilma API dokumentatsiooni lugemata.

• Asju üles otsida. Kliendid, ülesanded, ajakirjed, arved, lepingud, projektid, kontaktid, tiimid ja auditilogi on kõik käsurealt loetletavad ja avatavad. Otsi nime järgi või kleebi brauserist link, selle asemel et id-d jahtida. Kui nimi sobib rohkem kui ühe kirjega, keeldub CLI ja loetleb kandidaadid, selle asemel et arvata.
• Näha ülesannete nimekirjas päris tööd. Filtrita ülesannete nimekiri näitab tööd, mille inimene tööna ära tunneb. Võlunupu taimeriread ja mõlema tööplaani mootori mallread jäetakse välja ja kogusumma järgib sama reeglit. Küsi taimereid või malli ridu eraldi ja saad need kätte.
• Laadida tunnitabeli ühe päringuga. Kuni 200 ajakirjet lähevad üles koos, ühe tehinguna: kas kõik salvestatakse või mitte ükski. Üks tagasi lükatud rida tähendab, et midagi ei kirjutatud, ja CLI nimetab rea, mis selle põhjustas. Pooleldi laaditud tunnitabelit ei teki kunagi.
• Luua lepinguid ja neid laiali jagada. Leping ja kõik selle read luuakse ühe asjana. Eelvaade küsib serverilt, mis juhtuks, ilma et midagi kirjutataks, nii et näed enne otsustamist, mis loodaks ja mis tagasi lükataks. Malli laiali jagamine kliendinimekirjale on üks käsk ja iga klient, kellega ei õnnestunud, nimetatakse koos põhjusega.
• Webhooki tõrke põhjus üles leida. Loetle oma webhookid, vaata iga saatmiskatse kohta üht rida koos sellega, mida sinu lõpp-punkt vastas, saada üks sündmus uuesti või kustuta webhook. Webhooki loomist ja saladuse vahetamist CLI käskudena meelega ei ole. Mõlemad vastavad allkirjastamise saladusega, nii et käsk jätaks elava mandaadi sinu shelli ajalukku ja agendi transkripti.
• Leida arveldatavat tööd, mille arve juba lukku pani. Arveldamata töö aruanne käivitab lepinguliste klientide peal arveldusmootori enda, nii et see, mida ta näitab, ongi see, mida ümberarveldus päriselt küsiks. Aruanne on oma olemuselt aeglane, üks käik lepingulise kliendi kohta, seega piira see võimalusel ühe kliendiga.
• Aruandeid lugeda. Koondnäitajad, aegrida, jaotus ja tunnid kliendi või inimese kaupa tulevad tagasi tavaliste veergude ja ridadena, täpselt nii, nagu server need saatis.

Praeguse käsupinna saad käsuga uku --help. See artikkel meelega käske ei loetle — CLI enda abi genereeritakse sellest, mida tööriist päriselt teeb, ja koopia siin vananeks.

Võtme õigused on API õigused. CLI ei lisa omaenda õigusi ega võta midagi ära, seega otsustab võti, mille sa talle andsid, mida käsk teha tohib.

Võtme loomisel valid õiguste Lugemine, Muuda ja Kõik vahel ning otsustad eraldi, kas võti tohib finantsandmeteni ulatuda. See teine valik on omaette märkeruut, mitte osa õigusest, ja siin ongi see kasulik: lugemisõigus ja rahaligipääs on teineteisest sõltumatud. Päringu, mis puudutab finantsandmeid võtmega, millel finantsluba ei ole, lükkab API tagasi, ükskõik millist õigust võti kannab. See kontroll käib Ukus, mitte CLI-s.

Praktiline tagajärg agenditöö jaoks: anna koodiagendile Lugemine võti ja ta saab asju otsida ja küsimustele vastata, kirjutamised aga lükatakse tagasi. Lisa finantsluba ainult siis, kui töö päriselt vajab arve- või hinnaandmeid. Anna igale tööriistale ka oma võti, et saaksid ühe tühistada teisi häirimata. Täielik õiguste mudel, sealhulgas see, millised kirjed täpselt finantsandmeteks loevad, on artiklis Avalik API v3.

CLI kaudu kirjutamine on meelega tahtlik, mitte juhuslik, sest sama terminal, mis kliente loetleb, oskab ka arve saata.

• Kirjutamine väljaspool terminali vajab --yes. Käivita see ilma inimeseta — skriptis, CI-töös või agendis. Kirjutamine, mis selget kinnituslippu ei kanna, lükatakse tagasi, mitte ei tehta ära.
• Kirjutamine terminalis küsib üle. Sa kinnitad enne, kui midagi välja saadetakse.
• Kustutamine kordab oma sihtmärgi üle enne küsimist, nii et näed, milline kirje kohe kaob.
• Osalisest ebaõnnestumisest ei teatata kunagi kui õnnestumisest. Vahel võtab API päringu vastu, aga teatab, et mõned selle sees olevad kirjed kukkusid läbi. CLI nimetab need ebaõnnestumised ja lõpetab veaga, selle asemel et trükkida „tehtud” töö kohta, mida ei tehtud.
• Iga mitte-GET kirjutatakse kohalikku logisse CLI enda seadistuskataloogis, loetav ainult sinu kasutajakontole.

Seda logi tasub täpselt kirjeldada, sest just selle faili inimesed lisavad, kui midagi on valesti läinud. Iga kirjutamine lisab ühe tabulaatoriga eraldatud rea: aeg, milline konto oli kasutusel, meetod, päringu tee ilma päringustringita ja staatus, millega API vastas. Päringu- ega vastusekehasid seal ei ole, samuti mitte võtit. Kuna päringustring eemaldatakse, ei jõua faili kliendi nimi, mida otsisid. Küll aga jõuavad tees olevad kirjete id-d — kviitung peab ütlema, milline kirje muutus. Logi rotatsioon käib, kui see ületab viis megabaiti või kümme tuhat rida, ja alles jääb üks eelmine põlvkond.

Peaaegu mitte kunagi, ja erandi saab täpselt välja öelda. CLI saadab kirjutamise ise uuesti ainult siis, kui API vastas 428. See tähendab, et päring lükati tagasi versioonitempli puudumise pärast ja midagi ei muutunud. Selle uuesti saatmine on oma ehituselt ohutu — CLI tõmbab praeguse templi ja saadab päringu veel korra.

Iga muu ebaõnnestumine antakse sinu kätte, sest igal muul juhul on tulemus päriselt teadmata:

412 juhtumi loogika tasub endale selgeks teha: pime kordamine kirjutaks seal üle muudatuse, mille keegi just Ukus tegi. Lugemised on teine asi — need ei muuda midagi, seega tohib CLI lugemist korrata, kui ühendus ise katkes.

API võti avab sinu büroo elavad andmed, seega on CLI ehitatud nii, et võti jääks eemale kohtadest, kust mandaadid tavaliselt lekivad.

• See ei ole protsesside nimekirjas. Autentimispäised seatakse programmi sees, mitte argumentidena, nii et ükski ps väljund ei kanna võtit ajal, mil päring käib.
• See on väljundis maskitud. Olekuteated ja vead näitavad võtmest ainult katket. Ainus erand on käsk, mille kogu mõte on mandaat teise tööriista jaoks välja trükkida, ja see hoiatab veavoos iga kord.
• Ühendused on TLS 1.2 või parem ja tavaline http:// aadress lükatakse tagasi enne midagi saatmist, kui host ei ole sinu enda masin. Erand katab loopback-aadressid ja mitte midagi laiemat, nii et võti ei saa lahtiselt lahkuda sellepärast, et baas-URL sai valesti trükitud.
• Vaikimisi hostist erinev host annab endast teada. Kui CLI on kunagi suunatud mujale kui Uku enda API, trükib see ühe rea, mis nimetab hosti, kuhu sinu mandaadid kohe liiguvad. Vaikne lipp seda rida ei summuta. See, kuhu su võti läks, ei ole lobisemine, ja just seda rida on vaja näha inimesel, kes agenti valvab.

Koodiagendid õpivad CLI-d failist, mille CLI neile kirjutab. Käsk uku setup agents paigaldab oskusfaili Claude Code’i, Cursori ja Codexi jaoks ning ploki projekti AGENTS.md faili. Nii saab agent kätte käsud, veakoodide mudeli ja mis kõige tähtsam, ohutusreeglid, ilma et keegi peaks juhiseid vestlusse kleepima.

Sama töö jaoks on ka teine, elav kanal: --help --agent lisamine mis tahes käsule tagastab masinloetava kaardi selle käsu kohta. Need kaardid genereeritakse CLI enda käsupinnast, mitte ei kirjutata käsitsi. See ongi mõte: need ei saa kirjeldada käsku, mida ei ole, ega jääda maha käsust, mis muutus.

Mõlemad kanalid toetuvad negatiivsele teadmisele, sellele „see ei tööta nii, nagu sa eeldaksid” liigile, mis takistab agendil arvamast. Mida agent kõige sellega teha tohib, on endiselt piiratud võtmega, mille sa talle andsid.

Enamikul API toimingutest ei ole siin omaenda käsku ja see on otsus, mitte auk. Asjad, mida keegi ei skripti, jäävad sinna, kus inimene neid teeb: ettevõtte seadistamine, tööplaani malli koostamine, kliendile kirja saatmine. CLI ütleb seda otse, selle asemel et jätta sind mõistatama. Selle asemel ulatub uku api <MEETOD> <tee> iga sellise toiminguni, kasutades mandaate ja kirjutamise kinnitust, mille oled juba seadistanud. Nii ei jää puuduv käsk kunagi ette.

Käsurida, avalik API ja AI-assistent on kolm ust ühte API-sse, mitte kolm süsteemi. Õigused, päringute piirmäärad ja finantsvärav jõustatakse kõigi kolme taga ühes kohas ning kõik kolm kuuluvad Elite paketti.

Nende vahel valimine on peamiselt küsimus sellest, kelle käes tööriist on. Inimene, kes küsib küsimuse tavakeeles, tahab assistenti. Ajakava järgi jooksev tarkvara tahab API-t. Arendaja või koodiagent, kes töötab läbi muudatuste nimekirja, tahab käsurida. Uku AI-agentidele ja arendajatele võrdleb neid kõrvuti. Sinu andmed ja AI-assistendid katab selle, mida Uku salvestab ja mis liigub AI-teenusepakkujani, kui assistent on mängus.

Programm sai paigaldatud, aga sinu shell ei ole veel üles korjanud kausta, kuhu see läks. Ava uus terminaliaken ja proovi uuesti. Kui seda ikka ei leita, otsi shelli seadistusfailist rida, mille paigaldaja PATH-i jaoks lisas. Käivita see rida ise. uku doctor näitab, mida ta sinu PATH-is näeb.

Ühe rea paigaldaja katab macOS-i ja Linuxi nii Intelil kui ka Apple’i räni või ARM-i peal. Windowsis see peatub, selle asemel et pooleldi paigaldada: laadi Windowsi programm käsitsi väljalasete lehelt alla, nagu ülal kirjeldatud. Kõige muu peal ehita see lähtekoodist.

Ei. Ära käivita seda uuesti ja ära mine kontrollist mööda. Läbi kukkunud allkiri või sõrmejälg, mis allkirjastatud nimekirjaga ei ühti, näeb välja täpselt nii nagu võltsitud allalaadimine. See, et paigaldaja peatus, tähendab, et midagi ei paigaldatud. Teata sellest Ukule koos veateatega, mille paigaldaja trükkis.

Kirjutamine ilma inimeseta vajab --yes. Kui terminali, kus küsida, ei ole, keeldub CLI, selle asemel et järelevalveta tegutseda. Lisa käsule --yes või käivita see interaktiivselt ja kinnita viiba juures.

Sest sa küsisid kaks korda. Iga kirjutamine kannab idempotentsuse võtit, aga CLI loob igal käivitusel uue, seega on teine käivitus päriselt uus päring. Anna kaasa --idempotency-key enda valitud väärtusega ja kasuta kordamisel sama, või kasuta paljude muudatuste jaoks --batch koos --resume.