Uku CLI

Selle artikli lõpuks tead, milleks käsurida on, kuidas seda paigaldada, 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 midagi paigaldama ja pärast ehitamist ei vaja see sinu masinas ühegi asja kindlat versiooni. Ehitamiseks on vaja Go 1.26.5 või uuemat ja mitte midagi muud.

1. Klooni repositoorium: git clone https://github.com/uku-owl/uku-cli && cd uku-cli
2. Ehita see: scripts/build.sh, mis kirjutab bin/uku
3. Pane see oma PATH-i: cp bin/uku ~/.local/bin/ või mujale oma PATH-is
4. Kontrolli: uku --version ja pärast sisselogimist uku doctor

Ehitused tehakse macOS-ile ja Linuxile nii Inteli kui ka Apple’i või ARM-protsessoritele ning Windowsile Intelile.

Uku CLI sisselogimine on üks käsk, uku auth login, mis 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.

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 veaga 403 FINANCIAL_SCOPE_REQUIRED, ü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, ja anna igale tööriistale 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 — ja 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.
• 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 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:

API vastas	Mida see tähendab	Mida CLI teeb
428 — versioonitempel puudub	Kirjutamine lükati tagasi; midagi ei muutunud	Tõmbab templi ja saadab korra uuesti
412 — keegi teine muutis kirjet	Kirjutamine lükati tagasi; midagi ei muutunud	Peatub. Loe kirje uuesti, rakenda muudatus uuesti, kirjuta uuesti
429 — päringute piirmäär	Kirjutamise puhul on tulemus teadmata	Peatub. Kontrolli lugemisega, enne kui midagi muud saadad
5xx või ajalimiit	Tulemus teadmata	Peatub, samal põhjusel

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.

Uku CLI-l on varuväljapääs: uku api <MEETOD> <tee> saadab päringu mis tahes API v3 lõpp-punkti, kasutades mandaate ja kirjutamise kinnitust, mille oled juba seadistanud. Igapäevase töö jaoks on esmaklassilised käsud ja ülejäänu katab varuväljapääs, nii et puuduv käsk ei jää kunagi ette.

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.

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 ja Sinu andmed ja AI-assistendid katab selle, mida Uku salvestab ja mis liigub AI-teenusepakkujani, kui assistent on mängus.

curl -fsSL https://getuku.com/install-cli | sh peatub enne võrku pöördumist, ja see on meelega. Avaldatud paigaldaja pakub endiselt shelliskripti, mille see programm asendas. Selle käivitamine kirjutaks uku vana skriptiga üle ja teataks õnnestumisest. Ehita hoopis lähtekoodist, nagu ülal kirjeldatud.

Samal põhjusel. uku update tõmbab avaldatud paigaldaja ja kontrollib selle allkirja, seejärel peatub, selle asemel et anda sulle vana shelliskript. Uuemale versioonile liikumiseks ehita lähtekoodist uuesti.

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.