Σχεδιασμός AI Agent CLI: JSON, κωδικοί εξόδου και αναμονή

Ένα AI agent CLI δεν είναι απλώς ένα command-line εργαλείο για ανθρώπους που τυχαίνει να μπορεί να κληθεί από ένα model. Είναι ένα operational protocol. Το agent χρειάζεται deterministic inputs, structured outputs, ουσιαστικούς κωδικούς εξόδου, σταθερές κατηγορίες σφαλμάτων και έναν τρόπο να περιμένει μέχρι η asynchronous υποδομή να φτάσει σε τελική κατάσταση.

Χωρίς αυτό το contract, ένα agent αναγκάζεται να συμπεράνει την επιτυχία από διατυπώσεις όπως «το deployment ξεκίνησε». Αυτό το συμπέρασμα είναι επικίνδυνο, επειδή ένα accepted request μπορεί αργότερα να αποτύχει κατά το build, τα health checks, την εκκίνηση του container ή τη μεταφορά της κίνησης.

Γιατί είναι επικίνδυνο να υποθέτουμε ότι ένα deployment πέτυχε;

Οι περισσότερες infrastructure operations είναι asynchronous. Ένα API μπορεί να αποδεχτεί ένα deployment και να επιστρέψει ένα ID σε milliseconds, ενώ το πραγματικό build διαρκεί αρκετά λεπτά. Αν ένα agent αναφέρει επιτυχία στο acceptance boundary, κάθε επόμενο βήμα βασίζεται σε μια εσφαλμένη παραδοχή.

Δείτε τη διαφορά:

Event	Τι αποδεικνύει	Τι δεν αποδεικνύει
Το request έγινε αποδεκτό	Η πλατφόρμα κατανόησε το request	Ότι έγινε build του κώδικα
Το build ολοκληρώθηκε	Δημιουργήθηκε ένα image ή artifact	Ότι ξεκίνησε η εφαρμογή
Το health gate πέρασε	Το νέο instance ανταποκρίθηκε όπως απαιτείται	Ότι λειτουργούν τα business flows
Έγινε αλλαγή της κίνησης	Το release έγινε active	Ότι θα παραμείνει healthy
Παρατήρηση uptime	Η υπηρεσία παραμένει προσβάσιμη	Ότι κάθε feature λειτουργεί σωστά

Ένας άνθρωπος μπορεί να αντιληφθεί τη διαφορά σε ένα dashboard. Ένα agent που λειτουργεί μέσω κειμένου χρειάζεται αυτή η διάκριση να είναι κωδικοποιημένη στο interface.

Το contract εντολών του Dockup διαχωρίζει το queueing από την ολοκλήρωση. Ένα deploy χωρίς --wait επιστρέφει αμέσως με waited:false, ενώ ένα deploy με --wait μπλοκάρει μέχρι την επιτυχία, την αποτυχία ή το timeout:

dockup deploy production/api --wait --json

Το default timeout είναι 900 seconds. Η εντολή επιστρέφει 0 μόνο μετά από επιτυχημένη terminal state. Επιστρέφει non-zero με deploy_failed ή deploy_timeout όταν το αποτέλεσμα δεν είναι επιτυχία.

Τι προσφέρει σε ένα AI agent ένα structured JSON CLI;

Το structured JSON αντικαθιστά την ερμηνεία prose με named fields. Το agent μπορεί να εντοπίσει απευθείας τα status, deploymentId, target ή code, αντί να εξαρτάται από τη στίξη, τα χρώματα, το πλάτος των στηλών ή τη διατύπωση.

Ένα επιτυχημένο αποτέλεσμα μπορεί να καταναλωθεί ως data:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Ένα failure χρησιμοποιεί το ίδιο transport shape:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

Ο βασικός κανόνας σχεδιασμού είναι ότι το JSON γράφεται στο stdout, ενώ τα warnings που δεν πρέπει να αλλοιώνουν το parsing πηγαίνουν στο stderr. Τα logs σε follow mode χρησιμοποιούν NDJSON—ένα JSON object ανά γραμμή—ώστε ο caller να μπορεί να επεξεργάζεται το stream incremental χωρίς να περιμένει έναν τεράστιο array.

Το Dockup εφαρμόζει το `--json σε όλο το command surface. Με 135 commands, το να απαιτείται από ένα agent να συμπεραίνει flags από τη μνήμη θα ήταν brittle. Το CLI reference και το packaged skill παρέχουν τις command instructions που αντιστοιχούν στην έκδοση και πρέπει να ακολουθεί το agent.

Η σημαντική σχεδιαστική ιδιότητα δεν είναι το clever discovery. Είναι ότι το agent λαμβάνει τρέχουσες, structured operating οδηγίες και δεν επινοεί ένα flag από ένα παλιό prompt.

Πώς ελέγχουν τα πραγματικά exit codes το deployment automation;

Ο κωδικός εξόδου του operating system είναι το πιο portable signal επιτυχίας που είναι διαθέσιμο σε shell scripts, CI runners και coding agents. Το exit 0 σημαίνει ότι η εντολή πέτυχε το outcome που έχει οριστεί. Ένας non-zero κωδικός σημαίνει ότι ο caller πρέπει να κάνει branch σε recovery, escalation ή termination.

Αυτό το shell fragment είναι σκόπιμα απλό:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Δεν αναζητά τη λέξη “success” στο stdout. Δεν υποθέτει ότι μια HTTP 202 response σημαίνει πως το production είναι έτοιμο. Αναθέτει τον ορισμό της επιτυχίας στο CLI και μεταφέρει το failure στη parent process.

Τα πραγματικά exit codes είναι εξίσου σημαντικά για one-shot commands μέσα σε container. Η PRO εντολή exec του Dockup επιστρέφει stdout, stderr και τον πραγματικό κωδικό εξόδου της εντολής:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Έτσι, ένα agent μπορεί να διακρίνει ένα migration που ολοκληρώθηκε από μια εντολή που απλώς ξεκίνησε. Αυτή είναι θεμελιώδης αρχή των production guardrails για AI agents.

Πώς αντικαθιστά η αναμονή για terminal state το fragile polling;

Τα χειροποίητα polling loops εισάγουν κρυφές αποφάσεις πολιτικής: πόσο συχνά θα γίνεται polling, ποιες καταστάσεις είναι terminal, πόση ώρα θα περιμένουμε, αν ένα προσωρινό network error πρέπει να μηδενίζει τον timer και τι πρέπει να γίνει όταν ένα container κάνει restart.

Ένα agent είναι ιδιαίτερα πιθανό να κάνει λάθος σε αυτές τις αποφάσεις, επειδή μπορεί να μη γνωρίζει ολόκληρο το state machine της πλατφόρμας. Η πλατφόρμα πρέπει να αναλάβει τα semantics της αναμονής.

Το Dockup παρέχει δύο χρήσιμα patterns:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

Το deploy --wait περιμένει ρητά. Το push περιμένει από default μετά το push και το triggering του release· το --no-wait απενεργοποιεί αυτή τη συμπεριφορά. Και οι δύο εντολές επιστρέφουν exit code που αντικατοπτρίζει το terminal result.

Το log following ακολουθεί την ίδια ιδέα:

dockup logs production/api --build -f --json

Το stream ολοκληρώνεται όταν το build φτάσει σε success ή failure. Ένα τελικό NDJSON object σημειώνει done:true και ένα failed build επιστρέφει non-zero. Ο caller δεν χρειάζεται δεύτερη υλοποίηση polling.

Για τη διαθεσιμότητα της εφαρμογής μετά το deployment, η εντολή uptime του Dockup επιστρέφει checks ανά λεπτό, average response time και p95:

dockup uptime production/api --hours 24 --json

Η αναμονή και το monitoring είναι διαφορετικές έννοιες. Το --wait απαντά αν το συγκεκριμένο deployment έφτασε σε terminal result· το uptime απαντά πώς συμπεριφέρθηκε η running υπηρεσία με την πάροδο του χρόνου.

Ποιους error codes πρέπει να κατανοεί ένα agent;

Οι σταθερές κατηγορίες σφαλμάτων επιτρέπουν σε ένα agent να εκτελεί μια bounded ενέργεια χωρίς να ερμηνεύει κάθε πιθανό μήνυμα. Το Dockup εκθέτει codes όπως:

Error code	Σημασία	Ασφαλής απόκριση agent
not_logged_in	Δεν υπάρχει usable token	Διακοπή και αίτημα authentication
not_linked	Δεν υπάρχει .dockup target για push	Επίλυση ή παροχή του target
no_target	Δεν ήταν δυνατός ο εντοπισμός της υπηρεσίας	Εκτέλεση του services --json
needs_confirm	Η destructive action δεν έχει approval	Ερώτηση σε άνθρωπο
deploy_trigger_failed	Δεν ήταν δυνατή η έναρξη του deployment	Αναφορά του API error
deploy_failed	Το build ή το deploy απέτυχε	Ανάγνωση των build logs
deploy_timeout	Η διαδικασία εκτελείται ακόμη μετά το wait limit	Αναφορά αβεβαιότητας ή σκόπιμη παράταση

Το error message παραμένει χρήσιμο context, αλλά ο code καθορίζει το πρώτο branch. Έτσι, το automation παραμένει resilient σε πιο σαφή διατύπωση ή localization.

Η επιβεβαίωση αποτελεί επίσης μέρος του protocol. Μια destructive command δεν πρέπει να προχωρά σιωπηρά επειδή ο caller είναι non-interactive. Το Dockup αρνείται τέτοιες operations χωρίς --yes και επιστρέφει needs_confirm. Ένα autonomous agent βλέπει μια ερώτηση, όχι ένα εμπόδιο που πρέπει να παρακάμψει.

Το μοντέλο ασφάλειας αναλύεται περαιτέρω στις βέλτιστες πρακτικές ασφάλειας.

Ποιο είναι το ελάχιστο contract για ένα production-ready CLI;

Ένα production-ready AI agent CLI πρέπει να πληροί ένα μικρό αλλά αυστηρό contract:

1. Κάθε read και write operation διαθέτει machine-readable output.
2. Ένα failure παράγει non-zero process exit.
3. Τα asynchronous mutations μπορούν να περιμένουν documented terminal state.
4. Οι secret values δεν επιστρέφονται ποτέ από read commands.
5. Οι destructive actions απαιτούν explicit confirmation.
6. Τα errors διαθέτουν stable codes κατάλληλα για branching.
7. Το CLI package και οι agent instructions παραμένουν version-aligned.
8. Τα mutations καταγράφονται σε audit trail.

Το skill του Dockup μετατρέπει αυτούς τους κανόνες σε default behavior για τα Claude Code και Codex. Καθοδηγεί το agent να χρησιμοποιεί JSON, να κάνει authentication με DOCKUP_TOKEN, να εντοπίζει τα ακριβή targets, να κάνει deploy με --wait, να προστατεύει τα credentials και να σταματά στο needs_confirm.

Συγκρίνετε αυτό το μοντέλο με τις ευρύτερες έννοιες στο agent skills vs MCP. Ένα skill παρέχει operating knowledge· το CLI παραμένει το executable interface, του οποίου το exit status και το output ορίζουν την αλήθεια.

Ένα test matrix για command που απευθύνεται σε agent

Πριν εκθέσετε οποιοδήποτε infrastructure command σε ένα agent, ελέγξτε περισσότερα από το happy path:

Test	Αναμενόμενη συμπεριφορά
Valid request	JSON result και exit 0
Invalid token	Stable auth code και non-zero exit
Unknown target	Stable target code και no mutation
Long-running deploy	Αναμονή μέχρι terminal state ή timeout
Failed deploy	Non-zero exit και diagnosable deployment ID
Missing destructive approval	needs_confirm, no deletion
Secret read	Εμφανή key metadata, masked value
Warning κατά το JSON output	Warning στο stderr, valid stdout JSON

Αυτό το matrix είναι πιο πολύτιμο από ένα καλοσχεδιασμένο progress spinner. Το human formatting μπορεί να προστεθεί από πάνω· ένα deterministic machine contract δεν μπορεί να ανακατασκευαστεί εκ των υστέρων.

Η τεκμηρίωση του Dockup CLI παρουσιάζει τις συγκεκριμένες εντολές πίσω από αυτό το μοντέλο, ενώ το AI-powered development εξηγεί τη γενικότερη μετάβαση από τη χειροκίνητη χρήση εργαλείων σε agent-directed workflows.

Αντιμετωπίστε το observability ως μέρος του command contract

Ένα mutation που απευθύνεται σε agent πρέπει να επιστρέφει identifiers που καθιστούν δυνατή τη μεταγενέστερη διερεύνηση. Μια deployment response χρειάζεται το target και το deployment ID· μια created database χρειάζεται ένα stable slug· ένα volume snapshot χρειάζεται το snapshot ID του. Χωρίς αυτές τις αναφορές, το agent μπορεί να περιγράψει ένα event, αλλά δεν μπορεί να το επιθεωρήσει, να το επαναλάβει ή να το αναιρέσει με αξιόπιστο τρόπο.

Το audit trail ολοκληρώνει το contract. Το structured output εξηγεί μία invocation, ενώ τα audit records συνδέουν πολλές invocations με την πάροδο του χρόνου. Μαζί επιτρέπουν στους operators να απαντήσουν αν το agent ενήργησε στον σωστό resource και αν ένα μεταγενέστερο recovery command αναφερόταν στο ίδιο production event.

Κρατήστε το interface απλό

Ένα αξιόπιστο AI agent CLI πρέπει να είναι αναμενόμενο σε success, failure, timeout και retry.

Τελικός έλεγχος του interface

Το AI agent CLI πρέπει να αποτυγχάνει με ειλικρίνεια.

Περάστε το workflow σε production

Δοκιμάστε πρώτα το contract από ένα shell: επαληθεύστε το JSON parsing, ένα επιτυχημένο exit, ένα ελεγχόμενο failure, ένα timeout και μια blocked destructive operation, πριν αναθέσετε πρόσβαση σε production.

npm install -g dockup-cli
dockup skill install

Η πρώτη εντολή εγκαθιστά το CLI. Η δεύτερη εγκαθιστά το αντίστοιχο Dockup skill για τα Claude Code και Codex. Ξεκινήστε δωρεάν στο app.dockup.ai.

FAQ

Τι κάνει ένα CLI κατάλληλο για AI agents;

Χρειάζεται structured output, πραγματικούς κωδικούς εξόδου, αναμονή για terminal state, stable error codes, secret masking και explicit confirmation για destructive operations.

Γιατί είναι το JSON καλύτερο από το human-formatted CLI output για agents;

Το JSON παρέχει σταθερά field names και types. Το agent δεν χρειάζεται να συμπεράνει το νόημα από χρώματα, πίνακες, στίξη ή μεταβαλλόμενη prose.

Γιατί ένα accepted deployment request δεν αποτελεί επιτυχία;

Η αποδοχή αποδεικνύει μόνο ότι η πλατφόρμα έβαλε την operation σε queue. Το build, το startup, το health gate και το traffic cutover που ακολουθούν μπορούν ακόμη να αποτύχουν.

Ποιο είναι το default Dockup deployment wait timeout;

Το default timeout για το dockup deploy --wait είναι 900 seconds και μπορεί να αλλάξει με το documented --timeout option.

Πώς πρέπει να αντιδρά ένα agent στο needs_confirm;

Πρέπει να σταματήσει και να ζητήσει explicit approval. Ο code σημαίνει ότι η requested action είναι destructive και σκόπιμα δεν εκτελέστηκε.