devlift-cli 0.1.0__py3-none-any.whl

devlift_cli/MANUAL.md

@@ -0,0 +1,1066 @@
+# DevLift CLI manual
+
+`devlift` (alias `dl`) is the command-line tool for the DevLift platform. It
+works like the AWS CLI: `devlift <group> <operation> [flags]`. Every command
+is a fixed sequence of calls to the DevLift backend's REST API, the same
+endpoints the web dashboard uses. Nothing here talks to an AI model.
+
+Read this manual any time with `devlift man` (paged, like `man`: scroll,
+`/` to search, `q` to leave), or print one section with
+`devlift manual <topic>` (for example `devlift manual s3`).
+
+## 1. Install
+
+Requires Python 3.11 or newer. Nothing else: the installer puts DevLift in
+its own environment and touches no system packages.
+
+```
+curl -fsSL <install-url>/install.sh | sh
+```
+
+Or, from a wheel you were sent:
+
+```
+sh install.sh ./devlift_cli-<version>-py3-none-any.whl
+```
+
+It installs into `~/.local/share/devlift` and links `devlift` and `dl` into
+`~/.local/bin`, telling you if that is not on your PATH. Re-run it to
+upgrade. To remove it entirely:
+
+```
+rm -rf ~/.local/share/devlift
+rm -f ~/.local/bin/devlift ~/.local/bin/dl
+```
+
+Developers working on the CLI itself clone the repository and run
+`pip install -e .` inside a virtualenv instead.
+
+The login token is kept in the OS keyring when one is available, otherwise
+in `~/.config/devlift/credentials.json` with mode 0600.
+
+## 2. First run
+
+```
+devlift configure --base-url http://localhost:8000 --default   # where the backend runs
+devlift login                                                   # opens the browser
+devlift whoami                                                  # who you are, what the server enables
+```
+
+`configure` writes a profile to `~/.config/devlift/cli.json`. A profile is
+just a name, a backend URL and a default output format, and each one keeps
+its own sign-in.
+
+### Switching profiles
+
+```
+devlift profile list                 what you have; the default is starred
+devlift profile show                 which one this shell is using, and why
+devlift profile use prod             switch, now and for every later command
+```
+
+`profile use` changes the saved default, so it lasts until you change it
+again. For one command only, pass `--profile prod` anywhere on the line. For
+one shell session, export `DEVLIFT_PROFILE=prod`.
+
+A new profile is created by configuring a name that does not exist yet:
+
+```
+devlift --profile local configure --base-url http://localhost:8000
+devlift --profile local login
+```
+
+Two things override a switch, and `profile use` warns you when either is set.
+`DEVLIFT_PROFILE` beats the saved default, and `DEVLIFT_BASE_URL` replaces
+the backend of whichever profile is chosen. An exported `DEVLIFT_BASE_URL` is
+the usual reason a switch appears to do nothing, or why a command reports
+being signed in to one backend while targeting another. `devlift profile
+show` names the cause.
+
+## 3. Global options
+
+These work anywhere on the command line, before or after the subcommand.
+
+| Option | Meaning |
+|---|---|
+| `--profile NAME` | Use this profile (default: the one marked default, or `default`). |
+| `-o, --output table\|json\|yaml` | Output format. Table on a terminal, JSON when piped. |
+| `-y, --yes` | Answer yes to confirmations. |
+| `--no-input` | Never prompt. A missing value is an error (exit 3). Use in scripts and CI. Without `-y`, a write stops at its confirmation (exit 5) after printing its summary on stderr, in `-o json` mode too: a dry run. |
+| `--endpoint-url URL` | Override the backend URL for this one call. |
+| `--debug` | Log every HTTP call to stderr. |
+| `-V, --version` | Print the version. |
+| `-h, --help` | Help for any command. |
+
+Environment variables: `DEVLIFT_PROFILE`, `DEVLIFT_BASE_URL` (overrides the
+profile's backend), `DEVLIFT_TOKEN` (use this bearer token instead of the
+stored login), `DEVLIFT_OUTPUT`, `DEVLIFT_NO_CACHE=1` (skip the catalog
+cache), `DEVLIFT_CONFIG_DIR`.
+
+Note: a token belongs to the backend it was obtained from. If
+`DEVLIFT_BASE_URL` or `--endpoint-url` points elsewhere the CLI refuses with
+exit 2 and tells you to `devlift login` for that backend.
+
+## 4. Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Error (server error, unexpected failure) |
+| 2 | Not signed in, or the token is for another backend. Run `devlift login`. |
+| 3 | Missing or invalid input, or an ambiguous name |
+| 4 | Permission refused by the server |
+| 5 | Confirmation required (no `--yes` while `--no-input`) |
+| 6 | Not found |
+| 7 | Conflict: name already exists, wrong state, lane busy |
+
+Errors go to stderr as `error: <message>` plus an optional hint line. With
+`-o json` stdout carries only JSON, so `devlift … -o json | jq` is safe.
+
+## 5. Placement allowlist
+
+The backend lists every region for every application, which is wider than
+what exists. What each product, environment and region really offers is
+recorded per tenant in `devlift_cli/data/placement/{tenant}.json`, shipped
+inside this CLI:
+
+```
+{"<workspace>": {"<product>": {"<env>": {"<aws region>": ["s3", "sqs", ...]}}}}
+```
+
+Every create resolves its placement through that file, so a region the
+config does not list for that service is refused before anything is written:
+
+```
+error: s3 is not offered in 'canada' for core/stage.
+Available there: Mumbai.
+```
+
+`applications list`, `environments list` and `regions list` are filtered by
+it too, so what you are offered is what you can actually create in. They say
+how many rows they hid, and `--all` shows everything the backend reports:
+
+```
+devlift applications list            core          (falcon has no placement)
+devlift environments list            core/stage: Mumbai
+devlift regions list --for s3        Mumbai
+devlift regions list --all           Canada, London, Mumbai
+```
+
+Service keys are `s3`, `sqs`, `dynamo`, `eks`, `gateway` and `database`.
+Matching is on names, not codes: product `core`, environment `stage`, region
+`ap-south-1` resolved to its city label. A tenant with no file is not
+filtered at all, and filtering fails closed, so a bad match shows nothing
+rather than a placement that does not exist.
+
+The chatbot carries the same file at
+`backend/data/placement/{tenant}.json` and the dashboard a coarser copy.
+Change one, change the others.
+
+## 6. Names instead of codes
+
+Wherever a command takes `--app`, `--env`, `--region` or a service, you can
+type the name you see in the dashboard: `--app core`, `--env stage`,
+`--region mumbai`, `services describe java-service`. Matching is
+case-insensitive, exact first, then unique prefix. An ambiguous name is an
+error that lists the candidates. Codes are accepted too.
+
+Catalog answers are cached for ten minutes per profile. Add `--no-cache` to a
+list command, or set `DEVLIFT_NO_CACHE=1`, to refetch.
+
+## 7. Commands
+
+### auth
+
+```
+devlift login [--no-browser]     Sign in through the browser (OAuth 2.1, PKCE).
+devlift logout                   Revoke and forget the stored token.
+devlift whoami                   User, tenant, backend, enabled features.
+devlift configure [--base-url URL] [--default-output FMT] [--default] [--list]
+```
+
+`--no-browser` prints the sign-in URL instead of opening a browser. The
+login waits up to five minutes for the redirect.
+
+### applications, environments, regions, resource-types, resource-groups, repositories, languages
+
+```
+devlift applications list [--active] [--all]
+devlift environments list [--app NAME] [--all]  Environments and their regions per application.
+devlift regions list [--app NAME] [--env ENV]   Regions you can place resources in (the --region values).
+devlift regions list --for s3                   Only the regions that really offer that service.
+devlift regions list --all                      Skip the placement allowlist (section 5).
+devlift regions list --vendor aws               The cloud vendor's raw region list.
+devlift resource-types list [--family FAMILY]   Infrastructure types (storage, compute, network, …).
+devlift resource-groups list [--app NAME]       Resource groups; services are created inside one.
+```
+
+A resource group is the permission boundary a service lives in, so it
+decides who may later edit, approve and deploy that service. It is asked for
+by `eks create` when the application has more than one.
+
+### services
+
+```
+devlift services list [--app NAME] [--search TEXT]
+devlift services describe <name|code>
+```
+
+### repositories
+
+```
+devlift repositories list [--search TEXT]          Repositories the DevLift GitHub App can see (--repository values).
+devlift repositories branches <owner/name>         Branches of one repository (--branch values).
+```
+
+### languages
+
+```
+devlift languages list        Languages and versions a service can use (--language / --version values),
+                              and whether a starting template exists for each.
+```
+
+### clusters
+
+```
+devlift clusters list [--app NAME] [--env ENV] [--region REGION] [--type eks|ecs] [--search TEXT] [--all]
+```
+
+The clusters services run on, and the `--cluster` values for `eks create`.
+Narrowed to placements you could really create in: the backend reports only
+the environments this deployment serves, and the placement allowlist
+(section 5) says which of those offer EKS or ECS. Clusters outside both are
+real but unusable from here, so they are hidden and counted; `--all` shows
+everything the backend reports.
+
+```
+devlift clusters list --type eks --app core --env stage
+```
+
+```
+22 of 25 hidden: not a placement this deployment offers; --all shows everything.
+
+Cluster                                         Type  Environment  Region  Application  Registered
+acme-core-stage-mumbai-01-application-cluster  EKS   stage        Mumbai  core         yes
+…two more in the same placement, not registered
+```
+
+Within that, **Registered** is the flag that matters: only a registered
+cluster may take a new service, and `eks create` will not offer the others.
+A row whose Application reads "tenant-level" belongs to no single product
+and is the fallback for products with no cluster of their own.
+
+With exactly one registered cluster in a placement, `eks create` fills it in
+silently. With several it asks, or wants `--cluster` under `--no-input`.
+
+### s3
+
+```
+devlift s3 list [--app NAME] [--env ENV] [--region REGION]
+devlift s3 describe <bucket|code> [--env ENV]
+devlift s3 create --name NAME --app APP --env ENV --region REGION
+                  [--versioning | --no-versioning]
+                  [--replication --cross-account-id 123456789012 | --no-replication]
+                  [--wait] [-y]
+devlift s3 update <bucket|code> [--env ENV] [--app APP]
+                  [--versioning | --no-versioning]
+                  [--replication --cross-account-id 123456789012 | --no-replication]
+                  [--wait] [-y]
+```
+
+Every valid combination of the two settings, for `update` and for `create`,
+is listed further down this section.
+
+Section 8 walks a bucket through from the first flag to a finished
+deployment.
+
+Bucket names: 3-63 characters, lowercase letters, numbers, dots and hyphens,
+starting and ending with a letter or number. The backend prefixes the tenant
+and region on the real AWS name.
+
+`--replication` copies objects to another AWS account and needs
+`--cross-account-id` with that account's 12 digits. Either flag without the
+other is refused (exit 3).
+
+Every create also stores the AWS account and cloud region the resource sits
+in, which is what the dashboard canvas uses to place it. They are resolved
+automatically and printed in the summary. If they cannot be resolved the
+command says so before asking for confirmation: the resource would deploy
+normally but never appear on the canvas.
+
+`update` changes only the flags you pass. It reads the bucket, shows a
+Field | Current | New table, asks for confirmation, then queues and deploys
+the change exactly as `create` does (section 8). The name, application,
+environment and region cannot change — a bucket somewhere else is a new
+bucket. Passing values the bucket already has is reported and changes
+nothing.
+
+**Every combination.** Run each without `-y` first: the diff is printed and
+nothing is written (exit 5). Only the flags you pass change; the rest of the
+bucket is left alone.
+
+```
+# versioning
+devlift s3 update my-logs --versioning                 # turn it on
+devlift s3 update my-logs --no-versioning              # turn it off
+
+# replication
+devlift s3 update my-logs --replication --cross-account-id 123456789012
+devlift s3 update my-logs --cross-account-id 210987654321   # keep it on, change the target
+devlift s3 update my-logs --replication                # only if a target is already stored
+devlift s3 update my-logs --no-replication             # off, and the target is cleared
+
+# both at once: one diff, one confirmation, one deployment
+devlift s3 update my-logs --no-versioning --replication --cross-account-id 123456789012
+devlift s3 update my-logs --versioning --no-replication
+
+# doing it for real, and following the deployment
+devlift s3 update my-logs --no-versioning --replication --cross-account-id 123456789012 -y
+devlift s3 update my-logs --versioning -y --wait
+devlift s3 update my-logs --no-replication -y -o json
+```
+
+What each combination does:
+
+| Flags | Result |
+|---|---|
+| `--versioning` / `--no-versioning` | Versioning on or off. Nothing else touched. |
+| `--replication --cross-account-id ID` | Replication on, replicating to that account. |
+| `--cross-account-id ID` alone | Changes the target account, leaving replication as it is. |
+| `--replication` alone | Only works when the bucket already stores a target account. Without one: "Replication needs a target account" (exit 3). |
+| `--no-replication` | Replication off and the target account emptied, both shown in the diff. |
+| `--no-replication --cross-account-id ID` | Refused (exit 3). An account id means nothing with replication off. |
+| Values the bucket already has | "already has those values. Nothing to change", exit 0, `changed: false`. |
+| No flags at all | Refused (exit 3), listing the flags it accepts. |
+
+The same pairs apply to `create`, with one difference: there both
+decisions must be stated. On a terminal the command asks for anything you
+leave out; under `--no-input` a missing one is an error.
+
+```
+devlift s3 create --name my-logs --app core --env stage --region mumbai --versioning --no-replication
+devlift s3 create --name my-logs --app core --env stage --region mumbai --no-versioning --no-replication
+devlift s3 create --name my-logs --app core --env stage --region mumbai --versioning --replication --cross-account-id 123456789012
+devlift s3 create --name my-logs --app core --env stage --region mumbai --no-versioning --replication --cross-account-id 123456789012
+```
+
+`--app` and `--env` are normally unnecessary. `--env` only disambiguates a
+name that exists in several environments. `--app` is only needed when the
+backend does not report which application a resource belongs to and more
+than one could own it; otherwise the command infers it from the placement
+allowlist and says which it used.
+
+An update also repairs a resource that is missing the dashboard placement:
+if the stored record has no AWS account and cloud region, they are resolved
+and added, and the command says so. That is the fix for a resource created
+by an earlier version of this CLI that never appears on the canvas.
+
+### sqs
+
+```
+devlift sqs list [--app NAME] [--env ENV] [--region REGION]
+devlift sqs describe <queue|code> [--env ENV]
+devlift sqs create --name NAME --app APP --env ENV --region REGION
+                   [--fifo | --no-fifo] [--dlq | --no-dlq]
+                   [--cross-account-id ID ...]
+                   [--max-receive-count 1-1000] [--visibility-timeout 0-43200]
+                   [--retention 60-1209600] [--dlq-retention 60-1209600]
+                   [--wait] [-y]
+devlift sqs update <queue|code> [--env ENV] [--app APP]
+                   [--dlq | --no-dlq]
+                   [--cross-account-id ID ... | --clear-cross-accounts]
+                   [--max-receive-count 1-1000] [--visibility-timeout 0-43200]
+                   [--retention 60-1209600] [--dlq-retention 60-1209600]
+                   [--wait] [-y]
+```
+
+Queue names: letters, numbers, hyphens and underscores, at most 80
+characters, without the `.fifo` suffix (added automatically for FIFO queues).
+
+**Creating a queue.** Two decisions must be stated, FIFO and dead-letter
+queue. On a terminal the command asks for whichever you leave out; under
+`--no-input` a missing one is an error. Everything else is optional and
+falls back to the platform's defaults.
+
+```
+# the four basic shapes
+devlift sqs create --name orders --app core --env stage --region mumbai --no-fifo --no-dlq
+devlift sqs create --name orders --app core --env stage --region mumbai --no-fifo --dlq
+devlift sqs create --name orders --app core --env stage --region mumbai --fifo  --no-dlq
+devlift sqs create --name orders --app core --env stage --region mumbai --fifo  --dlq
+
+# a dead-letter queue with its retry budget and its own retention
+devlift sqs create --name orders --app core --env stage --region mumbai \
+    --no-fifo --dlq --max-receive-count 5 --dlq-retention 1209600
+
+# message timings
+devlift sqs create --name orders --app core --env stage --region mumbai \
+    --no-fifo --no-dlq --visibility-timeout 60 --retention 345600
+
+# other AWS accounts allowed to use the queue; repeat the flag per account
+devlift sqs create --name orders --app core --env stage --region mumbai \
+    --no-fifo --no-dlq --cross-account-id 123456789012 --cross-account-id 210987654321
+
+# everything at once, created for real and followed to the end
+devlift sqs create --name orders --app core --env stage --region mumbai \
+    --no-fifo --dlq --max-receive-count 5 \
+    --visibility-timeout 60 --retention 345600 --dlq-retention 1209600 \
+    --cross-account-id 123456789012 -y --wait
+```
+
+| Flag | Meaning | Accepted values |
+|---|---|---|
+| `--fifo` / `--no-fifo` | First-in-first-out ordering. Part of the real queue name, so it can never be changed later. | required |
+| `--dlq` / `--no-dlq` | Create a dead-letter queue beside this one. | required |
+| `--max-receive-count` | Receives before a message is moved to the dead-letter queue. | 1 to 1000 |
+| `--visibility-timeout` | Seconds a received message stays hidden from other consumers. | 0 to 43200 |
+| `--retention` | Seconds a message is kept. | 60 to 1209600 |
+| `--dlq-retention` | The same, for the dead-letter queue. | 60 to 1209600 |
+| `--cross-account-id` | A 12-digit AWS account allowed to use the queue. Repeat it for several. | repeatable |
+
+Refusals, all before anything is written (exit 3): a number outside its
+range, an account id that is not 12 digits, a name ending in `.fifo`, and a
+missing `--fifo` or `--dlq` under `--no-input`. Note that
+`--max-receive-count` is accepted with `--no-dlq`, but it has nothing to act
+on, since the count is what moves a message to a dead-letter queue.
+
+**Changing a queue.** `update` works like `s3 update`: only the flags you
+pass change, the diff is shown and confirmed, then the change is queued and
+deployed. The name, the FIFO flag, application, environment and region
+cannot change, since FIFO is part of the queue's real name.
+
+```
+devlift sqs update orders --dlq --max-receive-count 5      # add a dead-letter queue
+devlift sqs update orders --no-dlq                         # remove it
+devlift sqs update orders --visibility-timeout 120         # one timing
+devlift sqs update orders --retention 604800 --dlq-retention 604800
+devlift sqs update orders --cross-account-id 123456789012  # REPLACES the whole list
+devlift sqs update orders --clear-cross-accounts           # remove every grant
+devlift sqs update orders --dlq --max-receive-count 5 -y --wait
+```
+
+`--cross-account-id` on an update replaces the whole list rather than adding
+to it, so pass every account you want to keep. `--clear-cross-accounts`
+empties it, and the two cannot be combined.
+
+### dynamodb
+
+```
+devlift dynamodb list [--app NAME] [--env ENV] [--region REGION]
+devlift dynamodb describe <table|code> [--env ENV]
+devlift dynamodb create --name NAME --app APP --env ENV --region REGION
+                        --partition-key ATTR [--partition-key-type S|N|B]
+                        [--wait] [-y]
+```
+
+Table names: 3-200 characters of letters, numbers, dots, underscores and
+hyphens.
+
+**Creating a table.** Only the name and the partition key are yours to
+decide; the key type defaults to string. These are the same three fields the
+dashboard and the assistant ask for.
+
+```
+# the usual case: a string partition key
+devlift dynamodb create --name orders --partition-key order_id
+
+# a numeric or binary key
+devlift dynamodb create --name orders --partition-key created_at --partition-key-type N
+devlift dynamodb create --name orders --partition-key payload_id --partition-key-type B
+
+# spelled out in full, for a script
+devlift dynamodb create --name orders --app core --env stage --region mumbai \
+    --partition-key order_id --partition-key-type S
+
+# created for real and followed to the end
+devlift dynamodb create --name orders --partition-key order_id -y --wait
+```
+
+| Flag | Meaning | Accepted values |
+|---|---|---|
+| `--name` | Table name. | 3 to 200 characters, letters, numbers, dots, underscores, hyphens |
+| `--partition-key` | The attribute that partitions the table. | 1 to 255 characters, letters, numbers, dots, underscores, hyphens |
+| `--partition-key-type` | Its type. | `S` string (default), `N` number, `B` binary |
+
+Refusals, all before anything is written (exit 3): a name shorter than
+three characters or with other punctuation, a partition key with invalid
+characters, and a key type other than S, N or B. On a terminal the name and
+partition key are asked for when omitted; under `--no-input` they are
+errors.
+
+**There is no `dynamodb update`.** A table's partition key is fixed at
+creation and cannot be changed afterwards, so the command does not exist.
+Trying it exits 2 with "No such command". A different key means a different
+table.
+
+### eks
+
+```
+devlift eks create --name NAME --app APP --env ENV --region REGION --type api|worker
+                   [--resource-group GROUP] [--cluster CLUSTER]
+                   --repository owner/name --branch main [--branch ...]
+                   --language Go|Python|Node.js|"Java Maven"|"Java Gradle" --version 1.24
+                   [--set key=value ...] [--public] [-y]
+devlift eks settings                  Every key --set accepts, and when each applies.
+devlift eks settings <service>        Only the keys that apply to it, with its current values.
+devlift eks show <service> --env ENV  The configuration as it stands, with pending values marked.
+devlift eks diff <service> --env ENV  Preview the pending change: Field | Deployed | Requested.
+devlift eks diff <service> --deployed The live configuration versus the last deployment.
+devlift eks edit <service> --env ENV [--set key=value ...]
+                 [--repository owner/name] [--branch ...] [--language L --version V] [-y]
+```
+
+**Gather the answers first.** Placement resolves itself, but a service needs
+a resource group, a repository, a branch on it and a language version. Each
+has a command that lists the accepted values, so none of them has to be
+guessed:
+
+```
+# 1. the resource group that will own the service
+devlift resource-groups list --app core
+
+# 2. the repository the build reads, and a branch on it
+devlift repositories list --search admin
+devlift repositories branches example-org/admin-api-server
+
+# 3. the language and version
+devlift languages list
+
+# 4. the cluster, when the placement has more than one registered
+devlift clusters list --type eks --app core --env stage
+
+# 5. the settings --set accepts, and when each applies
+devlift eks settings                       # all of them
+devlift eks settings --language go --type api    # only the ones this service would use
+```
+
+The resource group is worth a moment: it is part of the service's
+permission path, so it decides who can later edit, approve and deploy it.
+Pick the team that owns the service rather than the default group. The
+repository must be one the DevLift GitHub App can see, and the branch must
+exist on it; both are checked before anything is written.
+
+**Then create it.** Run it once without `-y` to see the two tables, then
+again with `-y`:
+
+```
+devlift eks create --name orders \
+    --resource-group "Default service group" --type api \
+    --repo example-org/admin-api-server --branch main \
+    --language go --version 1.24
+
+devlift eks create --name orders \
+    --resource-group "Default service group" --type api \
+    --repo example-org/admin-api-server --branch main \
+    --language go --version 1.24 -y
+```
+
+Add `--app`, `--env` and `--region` to pin the placement, `--cluster` when
+more than one is available, and `--set key=value` for any setting you want
+to differ from the language template.
+
+**Add Kong routes, if the service needs them.** They join the same change
+set, so both halves are reviewed and deployed together:
+
+```
+devlift kong routes list orders                      # what it has now
+devlift kong route add orders --method GET --auth jwt --path '~/orders-service/health$'
+devlift kong route add orders --method GET --auth jwt --path '~/orders-service/health$' -y
+```
+
+**Preview what a reviewer will see:**
+
+```
+devlift eks diff orders --env stage     # one table per request, Deployed | Requested
+```
+
+**Then take it through review and deploy:**
+
+```
+devlift request submit orders          # freezes the diff, notifies approvers
+devlift approval approve orders        # needs can_approve
+devlift eks deploy orders --env stage  # prints the same preview, then asks
+devlift eks deploy orders --env stage -y --wait
+```
+
+**Then watch it land.** The deploy prints a workflow id; both of these read
+it back for you:
+
+```
+devlift eks status orders --env stage          # once
+devlift eks status orders --env stage --wait   # follow it to the end
+```
+
+`eks status` answers the two separate questions in one go: whether DevLift's
+pipeline finished, with its stages and pull request, and whether ArgoCD
+reports the pods actually serving. They are not the same moment. The
+pipeline turns green when the manifests are merged, and on a first deploy
+the image is still being built by GitHub Actions outside DevLift, so ArgoCD
+can report "waiting" for a while afterwards.
+
+By workflow id instead, or when you have lost it:
+
+```
+devlift deployment status <workflow-id> --wait
+devlift deployment list --status running
+devlift deployment list --limit 10
+```
+
+The service name becomes the Kubernetes namespace and the ECR repository,
+and cannot be renamed once deployed, so choose it before the first create.
+
+`eks create` creates a service and saves its first configuration as a **draft** for
+review. It is the dashboard's "Create & Add" followed by the Settings tab's
+Save, in one command:
+
+1. Register the service (`POST /services/create-service`): name, type,
+   application, resource group.
+2. Create its configuration row for that environment and region
+   (`POST /service-configs`) on the chosen EKS cluster. Only the placement
+   goes here: cluster, ALB selection (`api` uses the shared ALB, `worker`
+   has none) and namespace.
+3. Park the settings as a DRAFT queue item
+   (`POST /transaction/service-settings/<config>`), case `update_service`.
+
+Nothing is deployed. The draft goes through the review lane: `request
+submit`, `approval approve`, `eks deploy` (section "request, approval,
+eks deploy"), or the dashboard's Preview tab.
+
+**Values.** You give what no template can know: repository, branches,
+language and version. The repository must be one the DevLift GitHub App can
+see (`devlift repositories list`; a bare name is accepted when unique) and
+each branch must exist on it (`devlift repositories branches owner/name`).
+`--branch` is required: on a terminal the branches are listed and the
+repository's default branch is offered as the default answer; under
+`--no-input` a missing branch is an error (exit 3). `devlift languages list`
+shows the languages and versions. Every other setting (port, health and service paths,
+CPU and memory, replicas or autoscaling, Dockerfile options, IAM and the
+ECR/secrets/SSM/Argo flags) starts from the platform's template for that
+language, the same one the assistant applies. The full table is printed with
+a "From" column before you confirm. `--set key=value` overrides any of them;
+`devlift eks settings` lists the keys. Booleans are `true`/`false`, lists are
+comma-separated (`--set custom_iam_policies=s3,sqs`), build args are
+`NAME=VALUE` pairs (`--set build_args=APP_ENV=prod,REGION=ap-south-1`).
+Where the template has no reliable default, the command asks on a terminal,
+or exits 3 naming the `--set` key under `--no-input`.
+
+**Finding the `--set` keys.** `devlift eks settings` is the list, and naming
+a service narrows it to that service, adding the value each key holds today.
+That is the list to work from before an edit: what you can change, what it
+is now, and what values are accepted.
+
+```
+devlift eks settings orders --env stage
+
+orders (stage)
+Key            Setting              Values                       Current       Required
+port           Port                 text                         8080          yes
+alb_schema     ALB schema           internal | internet-facing   internal      yes
+cpu_limit      CPU limit (cores)    text                         0.25          yes
+go_config_path Go config path       text                         configs/…
+```
+
+`--language go --type api` narrows the same way without naming a service,
+which is what to use before a create. An unknown key is refused by `--set`
+with the full list, so a typo never reaches the backend.
+
+**Passing several settings.** Repeat the flag, or put them in one `--set`
+separated by semicolons. Both produce one diff, one confirmation and one
+deployment:
+
+```
+--set cpu_limit=0.5 --set memory_limit=0.5 --set port=9090
+--set "cpu_limit=0.5;memory_limit=0.5;port=9090"
+```
+
+The separator is a semicolon, not a comma, because a comma already
+separates the values inside one setting. The two nest cleanly:
+
+```
+--set "custom_iam_policies=s3,sqs;cpu_limit=0.5"   # one setting with two values, and another setting
+--set "build_args=APP_ENV=prod,REGION=ap-south-1;port=9090"
+```
+
+The semicolon form must be quoted, because a bare `;` ends the command in
+the shell. Repeated flags need no quotes, so use those if you would rather
+not quote. Commas need no quoting either.
+
+```
+--set "cpu_limit=0.5;port=9090"              # quoted: the shell would split it otherwise
+--set cpu_limit=0.5 --set port=9090          # no quotes needed
+--set custom_iam_policies=s3,sqs             # no quotes needed
+```
+
+**Per-language and conditional settings.** Not every key applies to every
+service; the rules are the platform form's own: `xms` / `xmx` only for Java,
+`go_config_path` / `go_use_aws_secrets` only for Go, `build_path` for Java
+and Go, `dockerfile_path` only with `generate_dockerfile=false`,
+`alb_schema` / `health` / `service_path` only for `--type api`,
+`min_replicas` / `max_replicas` only with `hpa_enabled=true` and
+`replica_count` only without it. `devlift eks settings` shows the table.
+A template value that does not apply falls away; a `--set` that does not
+apply is refused with the reason (exit 3). Values are checked the way the
+form checks them: CPU 0.1-4 cores and memory 0.1-8 GiB with limit >= request,
+replicas 1-100 with max > min, paths starting with `/`, heap sizes like
+`512m`, IAM policies from s3 / sqs / dynamodb / ses, build-arg names in
+uppercase. Service names are lowercase letters, numbers and hyphens.
+
+**Cluster.** The registered EKS cluster for that product, environment and
+region is picked automatically; tenant-level clusters are the fallback.
+Several candidates are asked for, or named with `--cluster`.
+
+A name that already exists in the application is refused (exit 7); adding a
+configuration in another environment for an existing service is not
+available yet.
+
+**Editing.** `eks edit` is the Settings tab's Save from the terminal. It
+starts from the configuration as it stands — the live values with your open
+draft, if any, laid over them — applies your changes, prints a Setting /
+Current / New table of only what changes, and saves the whole result as a
+settings draft (`POST /transaction/service-settings/<config>`). An open
+draft of yours is updated in place (same queue code), so repeated edits stay
+one request. A submitted or approved request on the service, whoever's,
+blocks editing (exit 7) until it is deployed, withdrawn or revoked: its
+values are being decided on. Passing values the service already has changes
+nothing. The same per-language and conditional rules as `eks create` apply.
+**Previewing a change.** `eks diff` is the preview: the pending request's
+own table of Field, Deployed and Requested, computed by DevLift against the
+live configuration. It is the same table the dashboard's Preview tab and the
+assistant render, so all three agree on what a reviewer will decide on. One
+table per request, since a service's settings and its gateway routes are two
+rows of one change.
+
+```
+devlift eks diff orders --env stage
+
+        orders (stage / Mumbai) · Settings · draft (queue-…, by a. developer)
+Field              Deployed   Requested
+port               –          8080
+health             –          /orders-service/health
+cpu_limit          –          0.25m
+```
+
+With nothing pending it says so. `--deployed` answers a different question,
+the redeploy drift: what the **live** configuration holds versus what was
+last deployed. That one ignores drafts entirely, so on a service whose
+change is still a draft it shows the live row and its defaults, not what the
+draft proposes.
+
+`eks show` marks each value that a pending request would change.
+
+### kong
+
+```
+devlift kong routes list  <service> [--env ENV] [--region REGION]
+devlift kong route add    <service> --env ENV --method GET --auth jwt|public
+                          --path '~/api/v1/orders$' [--path ...]
+                          [--tag TAG] [--priority 0-10000] [--plugin "User ID Injection"] [-y]
+devlift kong route remove <service> --env ENV --method GET --tag TAG --path '~/...$' [--path ...] [-y]
+devlift kong route rename <service> --env ENV --method GET --tag TAG --from '~/old$' --to '~/new$' [-y]
+devlift kong plugin add   <service> --env ENV --method GET --tag TAG --plugin "User ID Injection" [--priority N] [-y]
+```
+
+The gateway of one service configuration (environment + region), read and
+written the way the dashboard's Gateway tab does it. `routes list` shows
+the route groups: method, auth, tag, paths (with "not deployed" for paths
+that are still pending), regex priority, extra plugins and any pending
+queue items on the group.
+
+A change targets **one route group**: a tag for one HTTP method. `route add`
+creates the group when it does not exist, named after the service (`orders`
+for JWT, `orders-open` for public) unless `--tag` says otherwise. A tag is
+one group per method and its auth is fixed: adding a public path to a JWT
+tag is refused (exit 7), pick another tag. Paths already on the group are
+reported and skipped; a path to remove or rename that is not on the group is
+an error listing what is (exit 6). Nothing to change exits 0 with
+`changed: false`.
+
+Paths are Kong regex paths: start with `~/`, end with `$`, no spaces,
+parameters as regex groups (`~/api/v1/users/(?<id>[^/]+)$`, never `/:id`).
+Tags are letters, numbers, underscores and single hyphens. JWT comes from
+`--auth`; `--plugin` is for the extra plugins the tab offers.
+
+The change is printed and confirmed, then saved as a DRAFT queue item
+(`POST /transaction/kong-gateway/<config>`, the gateway half of the
+service's change set). Nothing reaches Kong until the draft is submitted,
+approved and deployed (`request submit`, `approval approve`, `eks deploy`).
+
+### request, approval, eks deploy — the review lane
+
+```
+devlift request list [--status draft|submit|approved|rejected] [--service NAME --env ENV] [--mine]
+devlift request show <queue-code|service> [--env ENV]
+devlift request history <service> [--env ENV]
+devlift request submit   <queue-code|service> [--env ENV] [--comment TEXT] [-y]
+devlift request withdraw <queue-code|service> [--env ENV] [--comment TEXT] [-y]
+devlift request discard  <queue-code|service> [--env ENV] [-y]
+
+devlift approval list
+devlift approval approve         <queue-code|service> [--env ENV] [--comment TEXT] [-y]
+devlift approval request-changes <queue-code|service> [--env ENV] --comment TEXT [-y]
+devlift approval reject          <queue-code|service> [--env ENV] --comment TEXT [-y]
+devlift approval revoke          <queue-code|service> [--env ENV] [--comment TEXT] [-y]
+
+devlift eks deploy <service> --env ENV [--region REGION] [--confirm-name NAME] [--wait] [-y]
+```
+
+A service's change is one **change set**: its settings request, its gateway
+routes request and its variables request, for one configuration and one
+author. Every verb moves the whole set, so naming a service acts on all of
+its rows, and the output lists each one. A queue code names its own set.
+
+```
+draft ──submit──▶ submit ──approve──▶ approved ──deploy──▶ in flight
+  ▲                 │ ▲                   │
+  └────withdraw─────┘ └──────revoke───────┘
+  └──request-changes──┘        reject ──▶ rejected (terminal)
+discard throws a draft away
+```
+
+- **submit** (author): the diff is frozen per row; a reviewer decides on
+  exactly that. One live request per service at a time: a second author is
+  told whose request holds the lane (exit 7).
+- **withdraw** (submitter only) and **request-changes** (reviewer, comment
+  required) both return the set to draft. **reject** (reviewer, comment
+  required) is terminal.
+- **approve** (needs `can_approve`; self-approval only where the resource
+  group's rule allows it) seals each row. **revoke** takes an approval back
+  while nothing has started deploying; the request waits for a decision
+  again.
+- **eks deploy** prints what is about to ship before it asks: the approved
+  requests, then each one's Field | Deployed | Requested table, the same
+  preview `eks diff` and the dashboard show. It ships the set with one call
+  (`POST /deployments/multiple-deploy {service_config_code}`): the backend
+  resolves the approved rows, re-checks the seal, and starts one workflow.
+  On **prod** the service name must be typed back (`--confirm-name` when
+  not on a terminal); `-y` alone is not enough. `--wait` follows the
+  orchestrator (variables, then the service) to completion.
+
+Each write prints the request(s) with the frozen diff, then confirms. `-o
+json` returns the rows and their new status. `request show` on a draft has
+no diff yet; the dashboard's Preview tab computes one live.
+
+### deployment, queue, eks status
+
+```
+devlift deployment list [--status running|completed|failed|timedout] [--app NAME] [--env ENV] [--mine] [--limit N]
+devlift deployment status <workflow-id> [--wait]   One deployment: status, PR, resources, pipeline stages.
+devlift eks status <service> --env ENV [--wait] [--no-argo]
+devlift queue list [--env ENV]                      Your transaction-queue items.
+```
+
+`deployment list` and `deployment status` read the same history the
+dashboard's deployment tracker shows: every workflow (resource creates,
+service deploys), who started it, its pull request, the resources it
+carried and the pipeline stages with their timings. `--wait` polls until
+the workflow reaches a terminal status.
+
+`eks status` answers two different questions for one service configuration:
+
+1. **Deployment** — did DevLift's pipeline finish? The latest workflow that
+   carried this configuration, with its stages and PR.
+2. **Application** — is the service actually serving? Asked of ArgoCD
+   (`GET /deployments/application-status`, the same implementation the
+   assistant uses). DevLift's pipeline turns green when the manifests are
+   merged, before ArgoCD rolls a pod, so the ArgoCD reading is compared
+   against the deploy's finish time: activity older than the deploy means
+   "waiting for ArgoCD", not "up". `state` is one of up, starting,
+   unhealthy, waiting_for_argocd, not_picked_up, missing, suspended,
+   not_found, not_configured (no ArgoCD for that environment), unavailable.
+   Health, sync, the running image, and the ArgoCD and health-check URLs
+   are shown when known. Note that DevLift never learns the image tag the
+   app repository built, so "up" means a healthy pod, not proof that the
+   new code is live.
+
+`--wait` follows the deployment to its end and then ArgoCD until the state
+settles (up to ten minutes). `--no-argo` skips the ArgoCD check.
+
+### manual
+
+```
+devlift man                This whole document, paged like `man` (scroll, / to search, q to leave).
+devlift manual [topic]     The same; with a topic, one section printed straight through (`devlift manual s3`).
+devlift manual --no-pager  The whole document without paging.  --raw prints plain Markdown.
+devlift <group> manual     This group's section, from inside the group (`devlift sqs manual`).
+```
+
+Every command group carries its own `manual`: `s3`, `sqs`, `dynamodb`,
+`eks`, `kong`, `request`, `approval`, `deployment`, `repositories` and
+`languages`. It prints exactly what `devlift manual <group>` prints, so it
+can be read without leaving the group you were typing in. `--raw` gives
+plain Markdown.
+
+## 8. Creating a bucket, start to finish
+
+The same five steps work for a queue or a table: swap `s3 create` for
+`sqs create` or `dynamodb create`.
+
+**1. Find the values for the flags.** Names are accepted everywhere, so this
+is only needed the first time.
+
+```
+devlift applications list                       # --app
+devlift environments list --app core            # --env, and the regions per environment
+devlift regions list --app core --env stage     # --region
+```
+
+All three are already filtered by the placement allowlist (section 5), so
+anything they list is somewhere a bucket can really go.
+
+**2. Choose the bucket's settings.** Two decisions, and both must be stated.
+
+```
+--versioning | --no-versioning                  keep old object versions
+--replication --cross-account-id 123456789012   copy objects to another AWS account
+--no-replication                                no copy
+```
+
+Replication needs a target account, so `--replication` without
+`--cross-account-id` is refused (exit 3), and `--cross-account-id` without
+`--replication` is refused too. The account id is the 12-digit AWS account
+that receives the copies, not the one the bucket lives in.
+
+**3. Dry run it.** Leave `-y` off. The command resolves everything, checks
+the name is free, prints the summary and stops before writing anything
+(exit 5).
+
+```
+devlift s3 create --name my-logs --app core --env stage --region mumbai \
+    --versioning --no-replication
+```
+
+With replication instead:
+
+```
+devlift s3 create --name my-logs --app core --env stage --region mumbai \
+    --versioning --replication --cross-account-id 123456789012
+```
+
+```
+              Create bucket
+Bucket               my-logs
+Application          core
+Environment          stage
+Region               Mumbai
+AWS account          111122223333
+Cloud region         ap-south-1
+Versioning           yes
+Replication          yes
+Replication account  123456789012
+```
+
+Check the AWS account and cloud region lines. They are what places the
+bucket on the dashboard canvas. If they are missing the command warns you,
+and the bucket will deploy but stay invisible on the canvas.
+
+**4. Create it for real.** Add `-y` to the same command. This registers the
+bucket, queues it, approves it and starts the deployment.
+
+```
+devlift s3 create --name my-logs --app core --env stage --region mumbai \
+    --versioning --replication --cross-account-id 123456789012 -y
+```
+
+```
+Registered bucket my-logs (INFRA_S3_1A2B3C4D).
+Deployment queued (workflow deploy-example-1a2b3c4d5e6f).
+
+Bucket         my-logs
+Resource code  INFRA_S3_1A2B3C4D
+Queue item     queue-5e6f7a8b9c0d
+Workflow       deploy-example-1a2b3c4d5e6f
+```
+
+Keep the workflow id. Adding `--wait` to the create does the next step for
+you.
+
+**5. Watch the deployment.** The backend opens a pull request and applies it.
+
+```
+devlift deployment status deploy-example-1a2b3c4d5e6f --wait
+```
+
+Without `--wait` it prints the current state once. With it, the command
+follows the workflow and returns when it is done or failed. The output
+names the status, the pull request, the resources in the deployment and
+each pipeline stage with its timing.
+
+Lost the id? The history is searchable:
+
+```
+devlift deployment list --limit 10
+devlift deployment list --status running
+```
+
+**6. Confirm the bucket exists.**
+
+```
+devlift s3 describe my-logs --env stage
+devlift s3 list --app core --env stage --region mumbai
+```
+
+`describe` shows the real AWS name, which carries a tenant and region
+prefix, so `my-logs` becomes something like
+`acme-core-stage-mumbai-01-my-logs`. On the dashboard canvas, search for
+the name you passed to `--name`.
+
+### What a create does underneath
+
+1. Resolve `--app`, `--env`, `--region` to backend codes, and the AWS
+   account and cloud region for the canvas.
+2. Validate the name locally, then ask the backend's duplicate check.
+3. Print a summary and ask for confirmation (`-y` skips it; `--no-input`
+   without `-y` exits 5).
+4. Register the resource (`POST /infrastructures`).
+5. Add it to the transaction queue and approve the item.
+6. Start the deployment (`POST /transaction-queue/deploy`). The backend
+   opens a pull request and applies it through its workflow; the command
+   returns as soon as the workflow is accepted.
+7. With `--wait`, poll the workflow until it finishes or fails.
+
+The output carries the resource code, the queue item code, and the workflow
+id or pull-request URL. Re-running the same create is refused as a
+duplicate (exit 7); use `describe` to see the existing resource.
+
+## 9. Scripting examples
+
+```
+# JSON for every service, filtered with jq
+devlift services list -o json | jq '.[] | select(.status=="active") | .service_name'
+
+# Fully non-interactive create; fails instead of prompting
+devlift s3 create --name my-logs --app core --env stage --region mumbai \
+    --versioning --no-replication --no-input -y -o json
+
+# The workflow id from that JSON, followed to the end
+devlift deployment status "$(devlift s3 create ... --no-input -y -o json | jq -r .workflow_id)" --wait
+
+# Use a CI token instead of a browser login
+DEVLIFT_TOKEN=... devlift whoami -o json
+
+# Follow a deployment started earlier
+devlift deployment status deploy-example-9f8e7d6c5b4a --wait
+```
+
+## 10. Troubleshooting
+
+- **exit 2, "Not signed in"**: run `devlift login`. If you set
+  `DEVLIFT_TOKEN`, it is used as-is and never refreshed.
+- **"Profile 'default' is signed in to X, but this command targets Y"**: an
+  environment variable or `--endpoint-url` changed the backend. Unset
+  `DEVLIFT_BASE_URL`, or `devlift login` against the new backend.
+- **"Could not connect"**: the backend at the profile's URL is not running.
+  Check `devlift configure --list`.
+- **`--wait` reports the status service is busy**: the backend's workflow
+  status route is unavailable; the deployment itself continues. Check later
+  with `devlift deployment status <workflow-id>`.
+- **Table output looks like JSON**: stdout is not a terminal, so JSON is the
+  default. Force a table with `-o table`.
+
+## 11. Not available yet
+
+Not available from the CLI, by design: **variables and secrets** (their
+draft lives partly in a store only the secret service may write, and
+secret values must never pass through a shell), use the dashboard's
+Variables tab. Planned but not implemented: `data query` and an interactive
+`shell`.