Three doors

Console, CLI and SDK are three doors to one API

Consolea web pageclick Create bucketfor exploring and one-off changesCLIa terminalaws s3api create-bucket --bucket logs-2026for scripts and pipelinesSDKyour codes3.create_bucket(Bucket='logs-2026')inside an applicationThe APIone HTTPS request:PUT logs-2026Storagethe bucketnow existsConsole, CLI and SDK are three doors to the same API.Whatever you can click you can script, because the console itself only calls the API. Use the consoleto explore, the CLI for scripts and pipelines, and an SDK inside application code. The example isAWS; the Azure CLI (az) and the Google Cloud CLI (gcloud) work in the same way.

Click, command or code: the same request reaches the same API.

CLI grammar

Every CLI has one grammar: tool, group, action, options

awsec2describe-instances--region eu-west-1the toolthe service or groupthe actionoptionsazvmlist--output tablegcloudcompute instanceslist--format=jsonghprlist--state opendockercontainerls--allEvery CLI has the same grammar: tool, group, action, options.Learn one and the others read the same way. Ask for help at any level to see what can come next:az vm --help, gh pr --help. Options choose the region, the account profile and the output format,and JSON output is what scripts consume.

Tool, group, action, options. Learn one, read them all.

CLI grammar · Going deeper · 1 of 2

Exit codes: how scripts know a command failed

With set -eupload the buildexit code 0update the serviceexit code 1print "deployed"never runsWithoutupload the buildexit code 0update the serviceexit code 1print "deployed"exit code 0says "deployed" after a failureEvery command ends with an exit code: 0 for success, anything else for failure.By default a shell script carries on after a failed command. Start scripts with set -e, or thestricter set -euo pipefail, so that the first failure stops them. A pipeline reads the same exitcodes to decide whether a step is green or red.

Exit code 0 is success. set -e stops a script at the first failure.

Output for scripts · Going deeper · 2 of 2

Filter and format in the CLI, so the script gets only what it needs

awsaws ec2 describe-instances --query 'Reservations[].Instances[].InstanceId' --output text--query takes JMESPath. Output: json (the default), text, table or yaml.azaz vm list --query "[].name" --output tsv--query takes JMESPath here too. Output: json (the default), jsonc, table, tsv, yaml or none.gcloudgcloud compute instances list --filter="status=RUNNING" --format="value(name)"Its own --filter and --format. The default is a table for people; ask for json, yaml, csv or value.ghgh pr list --state open --json number,title --jq '.[].number'Choose the fields with --json, then filter them with the built-in jq.Ask the CLI for only the fields you need, in a format made for scripts. Never parse the table meant for people.text and tsv give bare values with no quotes or brackets, ready for a shell loop; json goes to jq or to a program.--query is applied on your machine after the whole response has arrived. To make the service send less, filter at theAPI too: aws ec2 describe-instances --filters Name=tag:env,Values=dev. AWS CLI v2 opens a pager: set AWS_PAGER="" in scripts.

Use --query and a script-friendly output format. Never parse the table.

Credentials

Credentials are found in a fixed order; best is a role

Searched in this order. The first one found is used.An option on the command--profile prodyou choose, for this one commandEnvironment variablesAWS_ACCESS_KEY_ID ...set by a shell or a pipelineA profile in a file~/.aws/confignamed sets: dev, prodA role given to the machinenothing is storedshort-lived keys, rotated for youaws sts get-caller-identityanswers "who am I, and in which account?" Run it before anything destructive.CLI and SDK find credentials in a fixed order, and the safest ones are never typed.A profile is a named set of account, region and credentials, so one laptop can reach dev and prodwithout mixing them up. On a server or in a pipeline, attach a role instead: the platform hands outshort-lived keys, and there is no secret to leak.

Option, environment, profile, then the machine's role.

Three clouds · Going deeper

Each cloud has the same pieces under different names

AWSAzureGoogle CloudA person signs inaws sso loginaz logingcloud auth loginCode on a laptop(the same profile)(the az login session)gcloud auth application-default loginChoose the target--profile, AWS_PROFILEaz account set -s NAMEgcloud config set project NAMEWho am I?aws sts get-caller-identityaz account showgcloud auth listKey in environmentAWS_ACCESS_KEY_IDAZURE_CLIENT_SECRETGOOGLE_APPLICATION_CREDENTIALSIdentity of a machineIAM rolemanaged identityattached service accountThree clouds, one pattern: sign in, pick a target, check who you are, and on machines use an attached identity.Azure calls the target a subscription and Google Cloud a project; on AWS it is an account, reached through a profile.The SDKs search as the CLIs do: AWS SDKs read the same profiles, and DefaultAzureCredential and Google's ApplicationDefault Credentials each try the environment, the local sign-in and the machine's identity in a fixed order.

IAM role, managed identity, service account: one idea, three names.

Idempotency

A script you can safely run twice is one you can trust

After run 1After run 2After run 3create-serveran order: do this1 server2 servers3 serversensure web-01 existsa goal: make it so1 server1 server1 serverA script that is safe to run twice is a script you can trust.Scripts get rerun: after a timeout, after failing halfway, by a scheduler that fires twice. Anidempotent step looks at the current state and changes only what is missing. Give resources fixednames rather than generated ones, and treat "already exists" as success.

State a goal, not an order. Then a rerun changes nothing.

Waiters · Going deeper

The API answers before the work is done: wait for the state you need

id=$(aws ec2 run-instances ... \ --query 'Instances[0].InstanceId' --output text)aws ec2 wait instance-running --instance-ids "$id"aws ec2 associate-address --instance-id "$id" ...Example: an instance that takes 30 s to startpendingrunning0 s15 s30 sthe waiter checks every 15 s; the third check sees "running"ToolBy defaultTo change thatAWS CLI, boto3returns once the request is acceptedaws ec2 wait ... or ec2.get_waiter('instance_running')Azure CLIwaits until the operation has finished--no-wait, then az vm wait --createdgcloudwaits until the operation has finished--asyncTerraformwaits, with a time limit per resourcea timeouts block in the resource"Accepted" is not "ready". Wait for the state you need before the next step uses it.aws ec2 wait instance-running checks every 15 seconds and gives up after 40 checks, 10 minutes, with exit code 255.Do not use sleep 60 instead: too long on a good day, too short on a bad one. "Running" still only means the virtualmachine has started; for "the service answers", poll its health address the same way, with a limit.

Use a waiter, not sleep: it polls until the resource is ready, with a limit.

A whole task

A good script: no secrets, every page, safe to rerun

import boto3ec2 = boto3.client('ec2')pages = ec2.get_paginator('describe_instances').paginate( Filters=[{'Name': 'tag:env', 'Values': ['dev']}, {'Name': 'instance-state-name', 'Values': ['running']}])ids = [i['InstanceId'] for p in pages for r in p['Reservations'] for i in r['Instances']]if ids: ec2.stop_instances(InstanceIds=ids)print(f'stopped {len(ids)}')no keys here: found from the roleevery page, not only the firstthe API filters: only dev,and only running serverssafe to rerun: nothing left to stopa line for the logA good script holds no secrets, reads every page, is safe to rerun and says what it did.This one stops every running development server, for a nightly schedule. It uses everything from thelast four lessons: a list comprehension, API filters, pagination, a role and idempotency.

A role for credentials, a paginator for all pages, a filter for the target.

Lesson complete

You finished “CLIs and SDKs”

Nicely done.

Open in a new tab