devlift-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlift-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: DevLift command-line tool: create, change, review and deploy DevLift resources from the terminal.
 License: Proprietary
 Keywords: devlift,devops,deployment,infrastructure,cli
@@ -40,17 +40,29 @@ the same endpoints the web dashboard uses. Nothing here talks to an LLM.
 ## Install
 
 ```
-pip install devlift-cli
+pipx install devlift-cli
 ```
 
-Or, to keep it in its own environment and off your system Python:
+pipx gives the tool its own environment and puts `devlift` and `dl` on your
+PATH. If you do not have it:
 
 ```
-pipx install devlift-cli
+sudo apt install pipx      # Debian / Ubuntu
+brew install pipx          # macOS
+pipx ensurepath            # once, then reopen your terminal
 ```
 
-Upgrade with `pip install -U devlift-cli` (or `pipx upgrade devlift-cli`).
-Your profile and sign-in live in `~/.config/devlift` and survive upgrades.
+Upgrade with `pipx upgrade devlift-cli`. Your profile and sign-in live in
+`~/.config/devlift` and survive upgrades.
+
+**Using pip instead?** Do it inside a virtual environment. A plain
+`pip install devlift-cli` fails on recent Debian, Ubuntu and Fedora with
+`externally-managed-environment`, because those systems refuse to let pip
+touch the system Python.
+
+```
+python3 -m venv ~/.venvs/devlift && ~/.venvs/devlift/bin/pip install devlift-cli
+```
 
 Then:
 
@@ -61,9 +73,9 @@ devlift whoami
 devlift man
 ```
 
-Requires Python 3.11 or newer. To remove it: `pip uninstall devlift-cli`
-(or `pipx uninstall devlift-cli`). That leaves `~/.config/devlift`, so delete
-that too if you want your profiles and sign-in gone as well.
+Requires Python 3.11 or newer. To remove it: `pipx uninstall devlift-cli`.
+That leaves `~/.config/devlift`, so delete that too if you want your profiles
+and sign-in gone as well.
 
 Several backends? `devlift profile list`, `devlift profile use <name>` and
 `devlift profile show` switch between them and say which one is active.
@@ -92,14 +104,18 @@ Variables and secrets stay in the dashboard by design.
 
 ## Claude skill
 
-`skills/devlift/` teaches Claude (Claude Code or any Agent Skills host) to
-drive this CLI non-interactively. Install with:
+A Claude skill ships inside the package, teaching Claude (Claude Code or any
+Agent Skills host) to drive this CLI non-interactively. Install it with:
 
 ```
-ln -s "$(pwd)/skills/devlift" ~/.claude/skills/devlift      # personal
-# or copy it into a project's .claude/skills/devlift
+devlift skill install              # ~/.claude/skills/devlift, every project
+devlift skill install --project    # ./.claude/skills/devlift, this repo only
 ```
 
+Start a new Claude session afterwards to pick it up. `devlift skill status`
+says where it is installed and whether it still matches the CLI;
+`devlift skill install --force` refreshes it after an upgrade.
+
 ## Development
 
 Building, testing and cutting a release: see `CONTRIBUTING.md` in the source

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/README.md

@@ -12,17 +12,29 @@ the same endpoints the web dashboard uses. Nothing here talks to an LLM.
 ## Install
 
 ```
-pip install devlift-cli
+pipx install devlift-cli
 ```
 
-Or, to keep it in its own environment and off your system Python:
+pipx gives the tool its own environment and puts `devlift` and `dl` on your
+PATH. If you do not have it:
 
 ```
-pipx install devlift-cli
+sudo apt install pipx      # Debian / Ubuntu
+brew install pipx          # macOS
+pipx ensurepath            # once, then reopen your terminal
 ```
 
-Upgrade with `pip install -U devlift-cli` (or `pipx upgrade devlift-cli`).
-Your profile and sign-in live in `~/.config/devlift` and survive upgrades.
+Upgrade with `pipx upgrade devlift-cli`. Your profile and sign-in live in
+`~/.config/devlift` and survive upgrades.
+
+**Using pip instead?** Do it inside a virtual environment. A plain
+`pip install devlift-cli` fails on recent Debian, Ubuntu and Fedora with
+`externally-managed-environment`, because those systems refuse to let pip
+touch the system Python.
+
+```
+python3 -m venv ~/.venvs/devlift && ~/.venvs/devlift/bin/pip install devlift-cli
+```
 
 Then:
 
@@ -33,9 +45,9 @@ devlift whoami
 devlift man
 ```
 
-Requires Python 3.11 or newer. To remove it: `pip uninstall devlift-cli`
-(or `pipx uninstall devlift-cli`). That leaves `~/.config/devlift`, so delete
-that too if you want your profiles and sign-in gone as well.
+Requires Python 3.11 or newer. To remove it: `pipx uninstall devlift-cli`.
+That leaves `~/.config/devlift`, so delete that too if you want your profiles
+and sign-in gone as well.
 
 Several backends? `devlift profile list`, `devlift profile use <name>` and
 `devlift profile show` switch between them and say which one is active.
@@ -64,14 +76,18 @@ Variables and secrets stay in the dashboard by design.
 
 ## Claude skill
 
-`skills/devlift/` teaches Claude (Claude Code or any Agent Skills host) to
-drive this CLI non-interactively. Install with:
+A Claude skill ships inside the package, teaching Claude (Claude Code or any
+Agent Skills host) to drive this CLI non-interactively. Install it with:
 
 ```
-ln -s "$(pwd)/skills/devlift" ~/.claude/skills/devlift      # personal
-# or copy it into a project's .claude/skills/devlift
+devlift skill install              # ~/.claude/skills/devlift, every project
+devlift skill install --project    # ./.claude/skills/devlift, this repo only
 ```
 
+Start a new Claude session afterwards to pick it up. `devlift skill status`
+says where it is installed and whether it still matches the CLI;
+`devlift skill install --force` refreshes it after an upgrade.
+
 ## Development
 
 Building, testing and cutting a release: see `CONTRIBUTING.md` in the source

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/devlift_cli/MANUAL.md

@@ -875,6 +875,29 @@ the workflow reaches a terminal status.
 `--wait` follows the deployment to its end and then ArgoCD until the state
 settles (up to ten minutes). `--no-argo` skips the ArgoCD check.
 
+### skill
+
+The CLI ships with a Claude skill: instructions that teach Claude (Claude Code
+or any Agent Skills host) to drive these commands non-interactively, including
+the exit codes, the draft/review/deploy model and a command reference.
+
+```
+devlift skill install              Install it for your user (~/.claude/skills/devlift).
+devlift skill install --project    Install it into this repository (./.claude/skills/devlift).
+devlift skill install --force      Replace an existing installation; do this after upgrading.
+devlift skill status               Where it is installed, and whether it matches this CLI.
+devlift skill uninstall            Remove it.
+```
+
+Start a new Claude session after installing. Installing copies the files
+rather than linking them, because an upgrade replaces the environment the CLI
+lives in; `status` tells you when the copy has fallen behind, and
+`install --force` refreshes it.
+
+Installed for your user, the skill applies to every project on the machine.
+Installed into a repository and committed, everyone who clones it gets the
+skill without running anything.
+
 ### manual
 
 ```

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/devlift_cli/__init__.py

@@ -1,3 +1,3 @@
 """DevLift command-line tool."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/devlift_cli/app.py

@@ -29,6 +29,7 @@ from devlift_cli.commands import manual as manual_cmds
 from devlift_cli.commands import repositories as repositories_cmds
 from devlift_cli.commands import request as request_cmds
 from devlift_cli.commands import s3 as s3_cmds
+from devlift_cli.commands import skill as skill_cmds
 from devlift_cli.commands import sqs as sqs_cmds
 from devlift_cli.config import load_profile
 from devlift_cli.context import Invocation
@@ -82,6 +83,7 @@ app.command("logout")(auth_cmds.logout)
 app.command("whoami")(auth_cmds.whoami)
 app.command("configure")(auth_cmds.configure)
 app.add_typer(auth_cmds.profile_app, name="profile")
+app.add_typer(skill_cmds.skill_app, name="skill")
 app.command("manual")(manual_cmds.manual)
 # `devlift man` — the name every terminal user reaches for first. Hidden from
 # the command list so the manual appears once there, under its full name.

devlift_cli-0.1.2/devlift_cli/commands/skill.py

@@ -0,0 +1,158 @@
+"""devlift skill install — put the bundled Claude skill where Claude looks.
+
+The skill teaches Claude (Claude Code, or any Agent Skills host) to drive this
+CLI: the rules for calling it non-interactively, the intent-to-command map, the
+draft/review/deploy model, and a command reference.
+
+It ships inside the wheel rather than living only in the source repository,
+because the repository is private and the package is not. Someone who installed
+with `pipx install devlift-cli` can run this and have Claude know the commands;
+before, that needed a checkout nobody outside the team has.
+
+Installing COPIES the files rather than linking them. A pipx upgrade replaces
+the whole virtual environment, so a link into it is a link into something that
+gets rebuilt; a copy keeps working and `devlift skill install --force` after an
+upgrade refreshes it.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+import typer
+
+from devlift_cli import __version__
+from devlift_cli.context import Invocation
+from devlift_cli.errors import CliError
+from devlift_cli.render import output
+from devlift_cli.render.output import kv_table
+
+skill_app = typer.Typer(help="The Claude skill for driving this CLI.", no_args_is_help=True)
+
+SKILL_NAME = "devlift"
+# Every file the skill is made of. Listed rather than globbed so a missing one
+# is an error here instead of a skill that half-works inside Claude.
+SKILL_FILES = (
+    "SKILL.md",
+    "reference/commands.md",
+    "reference/exit-codes.md",
+    "reference/workflows.md",
+)
+
+
+def _personal_dir() -> Path:
+    return Path.home() / ".claude" / "skills" / SKILL_NAME
+
+
+def _project_dir() -> Path:
+    return Path.cwd() / ".claude" / "skills" / SKILL_NAME
+
+
+def _source_files() -> list[tuple[str, str]]:
+    """(relative path, contents) for the packaged skill."""
+    root = resources.files("devlift_cli").joinpath("skill")
+    out = []
+    for name in SKILL_FILES:
+        try:
+            out.append((name, root.joinpath(name).read_text(encoding="utf-8")))
+        except (FileNotFoundError, OSError) as exc:
+            raise CliError(
+                f"The installed package is missing its skill file '{name}'.",
+                hint="Reinstall devlift-cli, or report this as a packaging bug.",
+            ) from exc
+    return out
+
+
+@skill_app.command("install")
+def skill_install(
+    ctx: typer.Context,
+    project: bool = typer.Option(False, "--project", help="Install into ./.claude/skills instead of your home directory."),
+    path: str | None = typer.Option(None, "--path", help="Install into this directory instead."),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing installation."),
+):
+    """Install the Claude skill so Claude can drive this CLI.
+
+    Personal by default (~/.claude/skills/devlift), which covers every project
+    on this machine. `--project` installs into the current repository instead,
+    where committing it gives the whole team the skill on clone.
+
+    Re-run with --force after upgrading devlift-cli to refresh the copy.
+    """
+    inv: Invocation = ctx.obj
+    target = Path(path).expanduser() if path else (_project_dir() if project else _personal_dir())
+
+    files = _source_files()
+
+    if target.exists() and not force:
+        # A symlink here is almost always an older install pointing into a
+        # source checkout, and silently replacing it would be the wrong call.
+        kind = "symlink" if target.is_symlink() else "directory"
+        raise CliError(
+            f"A skill is already installed at {target} ({kind}).",
+            hint="Pass --force to replace it.",
+            code=7,
+        )
+
+    if target.is_symlink():
+        target.unlink()
+    elif target.exists():
+        shutil.rmtree(target)
+
+    for name, text in files:
+        destination = target / name
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(text, encoding="utf-8")
+
+    output.success(f"Claude skill '{SKILL_NAME}' installed to {target} (from devlift-cli {__version__}).")
+    output.info("Start a new Claude session to pick it up. Re-run with --force after upgrading devlift-cli.")
+    inv.emit(
+        {"name": SKILL_NAME, "path": str(target), "files": [n for n, _ in files], "version": __version__},
+        lambda d: kv_table(
+            [("Skill", d["name"]), ("Installed to", d["path"]), ("From", f"devlift-cli {d['version']}"), ("Files", str(len(d["files"])))]
+        ),
+    )
+
+
+@skill_app.command("uninstall")
+def skill_uninstall(
+    ctx: typer.Context,
+    project: bool = typer.Option(False, "--project", help="Remove from ./.claude/skills instead of your home directory."),
+    path: str | None = typer.Option(None, "--path", help="Remove from this directory instead."),
+):
+    """Remove an installed Claude skill."""
+    target = Path(path).expanduser() if path else (_project_dir() if project else _personal_dir())
+    if not target.exists() and not target.is_symlink():
+        output.info(f"Nothing installed at {target}.")
+        return
+    if target.is_symlink():
+        target.unlink()
+    else:
+        shutil.rmtree(target)
+    output.success(f"Removed {target}.")
+
+
+@skill_app.command("status")
+def skill_status(ctx: typer.Context):
+    """Show where the skill is installed, and whether it matches this CLI."""
+    inv: Invocation = ctx.obj
+    packaged = dict(_source_files())
+
+    rows = []
+    for label, target in (("personal", _personal_dir()), ("project", _project_dir())):
+        if target.is_symlink():
+            state = f"symlink -> {target.resolve()}"
+        elif not target.exists():
+            state = "not installed"
+        else:
+            try:
+                same = all(
+                    (target / n).read_text(encoding="utf-8") == text for n, text in packaged.items()
+                )
+            except OSError:
+                same = False
+            state = "up to date" if same else "differs from this CLI — run: devlift skill install --force"
+        rows.append({"scope": label, "path": str(target), "state": state})
+
+    inv.emit(rows, lambda d: kv_table([(r["scope"], f"{r['state']}\n{r['path']}") for r in d], title=f"Claude skill (devlift-cli {__version__})"))

devlift_cli-0.1.2/devlift_cli/skill/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: devlift
+description: Operate the DevLift platform from the terminal with the `devlift` CLI — create S3 buckets, SQS queues, DynamoDB tables and EKS services, edit service settings, add Kong routes, run the review lane (submit, approve, reject), deploy approved changes and check deployment and ArgoCD status. Use whenever a user asks to provision, configure, ship, review or check anything on DevLift and a shell is available; never fall back to aws/kubectl/terraform.
+---
+
+# DevLift CLI
+
+`devlift` (alias `dl`) is a deterministic command-line client for the DevLift
+backend: every command is a fixed sequence of REST calls, the same ones the
+web dashboard makes. It is not an assistant and holds no state between calls.
+Full reference: `devlift manual` (or `reference/commands.md` in this skill).
+
+## Rules for calling it
+
+1. **Always non-interactive.** Add `--no-input -o json` to every call. A
+   missing value is then exit 3 naming the flag, instead of a prompt that
+   never returns. Read stdout as JSON; messages and tables go to stderr.
+2. **`-y` only when the user asked for the action.** Without `-y`, a write
+   command does every lookup, prints its summary and stops at the confirmation
+   with exit 5. Use that as a dry run: run without `-y`, show the user what
+   would happen, then rerun with `-y` on their go-ahead. Creates and updates of
+   S3/SQS/DynamoDB start a real deployment; `eks deploy` ships to a cluster.
+3. **Production deploys need the name typed back:** `eks deploy … --env prod
+   --confirm-name <service>`. `-y` alone is refused.
+4. **Never secrets.** Variables and secrets are not in the CLI by design; send
+   the user to the dashboard's Variables tab. Never put a secret in a flag.
+5. **Names, not codes.** `--app core --env stage --region mumbai`,
+   `services describe orders`. Discover valid values with the list commands
+   before guessing; an unknown name lists the candidates. The list commands
+   are already narrowed to placements that really exist, so when only one
+   application, environment or region survives, a create resolves it without
+   being told — do not pass `--app/--env/--region` unless the user named one
+   or a command asks for it.
+6. **Exit codes decide the next step** (see `reference/exit-codes.md`):
+   0 ok · 1 error · 2 not signed in → tell the user to run `devlift login`
+   (needs a browser; do not run it unattended) · 3 bad or missing input ·
+   4 permission refused · 5 confirmation required · 6 not found · 7 conflict.
+7. **Check the manual before an unfamiliar command**; do not invent
+   subcommands or flags. `devlift <group> <op> -h` is cheap.
+
+## DevLift replaces the manual route
+
+When the user wants to deploy, ship, release, provision infrastructure or
+connect to a cloud resource, this CLI is the way. Do **not** fall back to,
+or suggest, any of these:
+
+- `git push`, GitHub Actions, `kubectl`, `terraform`, CI pipelines
+- `docker build` / `docker run` / Docker Compose, even for a local database
+- `aws` CLI commands (`aws s3 mb`, `aws dynamodb create-table`, …)
+- installing a database locally, or "create the bucket by hand in the console"
+
+That holds even when the repository already has a Dockerfile or a compose
+file. If you write code that reads an S3 bucket, a queue or a table,
+provision it in the same turn rather than leaving a TODO.
+
+## How to ask
+
+**Choices get a dialog.** Which application, which environment, api or
+worker, which language — ask with AskUserQuestion, one question per decision,
+with the real values from the list commands as the options.
+
+**Anything the user must SEE before deciding is text, and ends the turn.**
+The language template, a Current/New diff, the tables `eks deploy` prints
+before it asks: reply with that content as text, end with the written
+question, and stop. Do not open a dialog in the same turn — it covers the
+content and the user decides blind. They answer in their next message and
+you act on it then.
+
+**A write needs an explicit yes in this conversation.** Run it without `-y`,
+show what it printed, wait. Never infer consent from an earlier message, and
+never run a create or deploy with `-y` because it seemed implied.
+
+**Stop on a duplicate.** If a name already exists, say so and ask; do not
+configure a second one.
+
+## Use the project they are sitting in — but never silently
+
+Before asking for a repository, branch, language or name, read the working
+directory:
+
+| Look at | Gives |
+|---|---|
+| `git remote get-url origin` | the repository, matched against `devlift repositories list` |
+| `git rev-parse --abbrev-ref HEAD` | the branch |
+| `go.mod`, `package.json`, `pom.xml`, `build.gradle`, `pyproject.toml` | the language and often the version, matched against `devlift languages list` |
+| the repository or folder name | a suggested service name, lowercased, hyphenated |
+
+**Then ask before using any of it.** Detection is a suggestion, never a
+decision: the user may be sitting in one repository while creating a service
+for another. Put what you found in one AskUserQuestion, with three ways out:
+
+> I can see this project. Shall I use it?
+> - **Use these** — repository `Vance-Club/orders`, branch `main`,
+>   language Go 1.24, service name `orders`
+> - **Show me the options** — run `repositories list`, `languages list` and
+>   `resource-groups list` and let me pick
+> - Other — tell me what to use
+
+Spell out every value you detected in the option text, so "Use these" is an
+informed yes rather than a blind one. On "Show me the options", print the
+real lists and let them choose. Never pass a detected repository, branch,
+language or name to a command the user has not seen and agreed to.
+
+The resource group is never detectable, so it is always asked. Say what it
+decides when you ask: it is the permission boundary, so it determines who
+can later edit, approve and deploy the service.
+
+## What maps to what
+
+| User wants | Command |
+|---|---|
+| a bucket / queue / table | `devlift s3|sqs|dynamodb create --name … --app … --env … --region …` |
+| change a bucket or queue setting | `devlift s3|sqs update <name> --env … <flags>` |
+| a new service | `devlift eks create --name … --app … --env … --region … --type api|worker --repo owner/name --branch main --language Go --version 1.24 [--set k=v]` |
+| change a service's settings | `devlift eks edit <service> --env … --set k=v` (saves a draft) |
+| see a service's config | `devlift eks show <service>`, `devlift eks settings <service>` |
+| preview what a pending request changes | `devlift eks diff <service>` |
+| add / remove / rename a Kong route | `devlift kong route add|remove|rename <service> --env … --method … …` |
+| send a change for review | `devlift request submit <service>` |
+| review a change | `devlift approval list`, `approval approve|request-changes|reject|revoke <service>` |
+| ship an approved change | `devlift eks deploy <service> --env … [--wait]` |
+| is the deploy done / is the app up | `devlift eks status <service> --env …`, `devlift deployment status <workflow-id> --wait` |
+| what exists | `applications|environments|regions|resource-groups|services|repositories|languages|clusters list`, `repositories branches owner/name` |
+
+Recipes with the exact sequence of calls and what to read from each result
+are in `reference/workflows.md`.
+
+## The model behind the commands
+
+- **Resources (S3, SQS, DynamoDB)** deploy directly: create/update registers
+  the row, queues it, approves it and starts the deployment in one command.
+  `--wait` follows the workflow; otherwise the result carries `workflow_id`
+  for `deployment status`.
+- **Services and Kong routes** never deploy directly. `eks create`, `eks edit`
+  and `kong route …` each save a **draft** queue row. A service's settings
+  row and gateway row form one **change set** and move together through the
+  review lane: `request submit` → `approval approve` → `eks deploy`. Naming a
+  service acts on the whole set; the output lists every row that moved.
+- **Templates fill settings.** `eks create` needs only what no template can
+  know (repository, branches, language, version). Port, paths, CPU, memory,
+  replicas and the rest come from the platform's per-language template and
+  are printed with a "From" column before the confirmation; `--set key=value`
+  overrides any of them, `devlift eks settings` lists the keys and when each
+  applies (JVM heap only for Java, Go config only for Go, health/service path
+  only for API services, min/max replicas only with autoscaling).
+- **Two status questions.** `deployment status` says whether DevLift's
+  pipeline finished; `eks status` also asks ArgoCD whether the pod is serving,
+  and reports "waiting for ArgoCD" when Argo has not acted since the deploy.
+
+## Creating a service: the conversation
+
+1. **Collect what only the user knows.** Detect what you can from the
+   project and offer it as above, then ask for the rest: service name, type
+   (api or worker) and resource group. Application, environment and region
+   usually resolve themselves, so do not ask unless a command asks you.
+   Offer real values from `repositories list`, `repositories branches`,
+   `languages list` and `resource-groups list` rather than guessing; a wrong
+   name costs a round trip and exit 6.
+2. **Dry-run** `eks create … --no-input -o json` without `-y`. It exits 5
+   and prints two tables on stderr: the service (placement, cluster it
+   picked, repository, branches, language) and the Configuration table with
+   a "From" column saying which values came from the language template.
+3. **Show the user those template values as they were printed and ask:**
+   "These are the standard <language> values. Apply them, or tell me what to
+   change?" That reply is text and ends the turn — no dialog, no tool call,
+   because a dialog would hide the table they are deciding on. Do not rerun
+   with `-y` until they answer.
+4. A change ("port 9000", "1 GiB memory limit", "turn on autoscaling 2 to 4")
+   becomes `--set` flags on the rerun: `--set port=9000`,
+   `--set memory_limit=1`, `--set hpa_enabled=true --set min_replicas=2
+   --set max_replicas=4`. Rerun without `-y` once more only if the change is
+   large; otherwise rerun with `-y` and report the service, configuration and
+   queue codes.
+5. Say it is a **draft** and name the next step: `request submit`, then a
+   reviewer's `approval approve`, then `eks deploy`.
+
+The same show-then-ask shape applies to every write: `eks edit` and the
+update commands print Current | New, `kong route …` prints the route change,
+the review verbs print the request with its frozen diff, `eks deploy` lists
+the approved rows. The summary is printed on every dry run, in json mode too.
+
+## Reporting back to the user
+
+- After a dry run (exit 5) show the summary the command printed and ask for
+  the go-ahead. After a write, report the codes it returned: resource code and
+  workflow id for resources; queue code and status for drafts and review
+  verbs; workflow id for a deploy.
+- A draft is not deployed. Say so, and name the next command
+  (`request submit`, then `approval approve`, then `eks deploy`).
+- On exit 7 quote the message: it names the conflicting request or the rule
+  (one live request per service, one auth per Kong tag, a name that exists).
+- On exit 2 stop and tell the user to sign in; on exit 4 say who to ask.

devlift_cli-0.1.2/devlift_cli/skill/reference/commands.md

@@ -0,0 +1,162 @@
+# Command reference (condensed from `devlift manual`)
+
+Global options work anywhere on the line: `--profile NAME`, `-o json|table|yaml`,
+`-y/--yes`, `--no-input`, `--endpoint-url URL`, `--debug`, `-h`. Environment:
+`DEVLIFT_PROFILE`, `DEVLIFT_BASE_URL`, `DEVLIFT_TOKEN` (CI token, used as-is),
+`DEVLIFT_OUTPUT`, `DEVLIFT_NO_CACHE=1`.
+
+## Identity and discovery
+
+```
+devlift whoami                                  user, tenant, backend, enabled features
+devlift profile list                            profiles; the default is starred
+devlift profile show                            which profile this shell uses, and why
+devlift profile use NAME                        switch the default profile (lasts until changed)
+devlift applications list [--active]
+devlift environments list [--app NAME]          environments and their regions per application
+devlift regions list [--app NAME] [--env ENV]   the --region values
+devlift resource-groups list [--app NAME]
+devlift resource-types list [--family FAMILY]
+devlift services list [--app NAME] [--search TEXT]
+devlift services describe <name|code>
+devlift repositories list [--search TEXT]       the --repository values (GitHub App visibility)
+devlift repositories branches <owner/name>      the --branch values
+devlift languages list                          the --language / --version values, template yes/no
+devlift eks settings                            the --set keys: values, when each applies, required
+```
+
+Catalog answers are cached ten minutes per profile; `--no-cache` on a list
+command or `DEVLIFT_NO_CACHE=1` refetches.
+
+## Resources (deploy directly)
+
+```
+devlift s3 list [--app] [--env] [--region]      devlift s3 describe <bucket|code> [--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] [--versioning|--no-versioning] [--replication --cross-account-id ID|--no-replication] [--wait] [-y]
+
+devlift sqs list / describe (same shape)
+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] [--dlq|--no-dlq] [--cross-account-id ID ...|--clear-cross-accounts]
+                   [--max-receive-count N] [--visibility-timeout N] [--retention N] [--dlq-retention N] [--wait] [-y]
+
+devlift dynamodb list / describe
+devlift dynamodb create --name NAME --app APP --env ENV --region REGION --partition-key ATTR [--partition-key-type S|N|B] [--wait] [-y]
+```
+
+Sequence behind create/update: duplicate check → `POST /infrastructures`
+(upsert with `code` on update) → add to queue → approve → deploy → optional
+wait. Result JSON: `resource_code`, `queue_code`, `status`, `workflow_id` or
+`pr_url`. Update prints Field | Current | New and sends the full merged
+config; name, application, environment, region (and FIFO for SQS) cannot
+change. Bucket names 3-63 lowercase/digits/dots/hyphens; queue names ≤80
+chars without `.fifo`; table names 3-200 chars, immutable after creation.
+
+## EKS services (save drafts)
+
+```
+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 show <service> --env ENV            configuration as it stands; pending values marked
+devlift eks diff <service> --env ENV            preview the pending request: Field | Deployed | Requested
+devlift eks diff <service> --deployed           instead: live config vs the last deployment
+devlift eks settings <service> --env ENV        the --set keys that apply to it, with current values
+devlift clusters list [--type eks] [--app] [--env]   the --cluster values (Registered = may take a service)
+devlift eks edit <service> --env ENV [--set key=value ...] [--repository owner/name] [--branch ...] [--language L --version V] [-y]
+devlift eks deploy <service> --env ENV [--region R] [--confirm-name NAME] [--wait] [-y]
+devlift eks status <service> --env ENV [--wait] [--no-argo]
+```
+
+- create = `POST /services/create-service` → `POST /service-configs`
+  (placement only) → `POST /transaction/service-settings/<config>` (DRAFT).
+  Result JSON: `service_code`, `service_config_code`, `queue_code`,
+  `queue_status`, `config`.
+- Service name: lowercase letters, digits, hyphens. Repository must be visible
+  to the GitHub App (bare name accepted when unique); each branch must exist.
+- Several settings go in one `--set` separated by semicolons
+  (`--set "cpu_limit=0.5;port=9090"`, quoted), or repeat the flag. A comma
+  separates values INSIDE one setting, so the two nest:
+  `--set "custom_iam_policies=s3,sqs;port=9090"`.
+- `--set` keys (booleans `true|false`, lists comma-separated, build args
+  `NAME=VALUE,…`): port, health, service_path, build_path, dockerfile_path,
+  go_config_path, xms, xmx, alb_schema (internal|internet-facing), compute
+  (on-demand|spot), auth_mode (pod_identity|irsa), cpu_requested, cpu_limit,
+  memory_requested, memory_limit (cores / GiB; 0.1-4 / 0.1-8; limit ≥ request),
+  replica_count, hpa_enabled, min_replicas, max_replicas (1-100, max > min),
+  generate_dockerfile, go_use_aws_secrets, create_ecr, create_secrets,
+  create_ssm, create_argo, other_paths, custom_iam_policies (s3,sqs,dynamodb,ses),
+  build_args.
+- Conditional: xms/xmx Java only; go_config_path/go_use_aws_secrets Go only;
+  build_path Java+Go; dockerfile_path only with generate_dockerfile=false;
+  alb_schema/health/service_path API only (required there); min/max with
+  hpa_enabled=true; replica_count with hpa_enabled=false. A `--set` that does
+  not apply is refused (exit 3); a template value that does not apply falls away.
+- edit: live config + your open draft → Current | New → settings draft,
+  reusing the open draft's queue code. Blocked (exit 7) while a submitted or
+  approved request exists on the service.
+- deploy = `POST /deployments/multiple-deploy {service_config_code}`: the
+  backend resolves the approved rows, re-checks the seal, starts one workflow.
+  Result JSON: `workflow_id`, `requests[]`. Prod: `--confirm-name`.
+- status: latest deployment for the configuration (stages, PR) plus ArgoCD
+  `state` (up | starting | unhealthy | waiting_for_argocd | not_picked_up |
+  missing | suspended | not_found | not_configured | unavailable), health,
+  sync, running image, URLs. `settled: false` means polling would change it.
+
+## Kong routes (save drafts)
+
+```
+devlift kong routes list  <service> [--env ENV] [--region R]
+devlift kong route add    <service> --env ENV --method GET|POST|PUT|PATCH|DELETE|OPTIONS --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 M --tag TAG --path '~/...$' [--path ...] [-y]
+devlift kong route rename <service> --env ENV --method M --tag TAG --from '~/old$' --to '~/new$' [-y]
+devlift kong plugin add   <service> --env ENV --method M --tag TAG --plugin "User ID Injection" [--priority N] [-y]
+```
+
+One change = one route group (tag × method). Default tag: the service name
+for JWT, `<service>-open` for public. A tag has one auth; mixing is exit 7.
+Paths: `~/…$`, no spaces, params as regex groups `(?<id>[^/]+)`, never `/:id`.
+Already-present paths are skipped; removing/renaming an absent path is exit 6.
+Write = `POST /transaction/kong-gateway/<config>` (DRAFT, gateway half of the
+service's change set). Result JSON: `changed`, `change{}`, `queue_code`.
+
+## Review lane
+
+```
+devlift request list [--status draft|submit|approved|rejected] [--service NAME --env ENV] [--mine]
+devlift request show <queue-code|service> [--env ENV]        frozen diff (Field | From | To)
+devlift request history <service> [--env ENV]
+devlift request submit|withdraw|discard <queue-code|service> [--env ENV] [--comment TEXT] [-y]
+devlift approval list                                         reviewer inbox by service
+devlift approval approve|revoke <queue-code|service> [--env ENV] [--comment TEXT] [-y]
+devlift approval request-changes|reject <queue-code|service> [--env ENV] --comment TEXT [-y]
+```
+
+States: draft →submit→ submit →approve→ approved →deploy→ in flight.
+withdraw (submitter) and request-changes (reviewer, comment) return to draft;
+reject (reviewer, comment) is terminal; revoke returns approved to submit
+while nothing is deploying; discard bins a draft. Every verb moves the whole
+change set (settings + gateway rows of one author); one live request per
+service at a time. Result JSON: `requests[] {code, kind, status}`.
+
+## Deployments
+
+```
+devlift deployment list [--status running|completed|failed|timedout] [--app NAME] [--env ENV] [--mine] [--limit N]
+devlift deployment status <workflow-id> [--wait]     status, PR, resources, pipeline stages
+devlift queue list [--env ENV]                        your transaction-queue items
+```
+
+Terminal statuses: COMPLETED, FAILED, TIMEOUT, CANCELLED. Stage rows carry
+name, status, started_at, ended_at, error.
+
+## Not in the CLI
+
+Variables and secrets (dashboard Variables tab only, by design), `data
+query`, interactive shell.

devlift_cli-0.1.2/devlift_cli/skill/reference/exit-codes.md

@@ -0,0 +1,16 @@
+# Exit codes and what to do
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | Success | Read stdout JSON. A write returns codes (resource, queue item, workflow). `changed: false` means nothing needed doing. |
+| 1 | Error | Server-side or unexpected failure. Quote `error:` from stderr. Retry once only if it reads as transient (status service busy). |
+| 2 | Not signed in, or the token belongs to another backend | Stop. Tell the user to run `devlift login` in their terminal (opens a browser). If stderr says "signed in to X, but this command targets Y", the shell exports `DEVLIFT_BASE_URL`; unset it or log in to that backend. |
+| 3 | Missing or invalid input | The message names the flag or key. Fix and rerun. Includes an ambiguous name (candidates are listed), a `--set` that does not apply to this language/service type, a value out of range, a missing `--comment` on reject/request-changes. |
+| 4 | Permission refused by the server | The user lacks the OpenFGA relation (can_write_settings, can_approve, can_deploy…). Say so; do not retry. |
+| 5 | Confirmation required | Expected on every write without `-y` under `--no-input`. Show the printed summary, get the user's yes, rerun with `-y`. |
+| 6 | Not found | Unknown service, bucket, queue code, repository, branch, cluster, or no request in the state the verb needs ("No draft request of yours on X"). |
+| 7 | Conflict | Name already exists; request in the wrong state ("is approved — only submitted can be…"); another author's request holds the service's review lane; Kong tag already has the other auth; deployment already in progress. Quote the message, it says what to do. |
+
+Stderr format is always `error: <one sentence>` followed by an optional hint
+line. With `-o json`, stdout carries JSON only, so it is safe to parse even
+when stderr has messages.

devlift_cli-0.1.2/devlift_cli/skill/reference/workflows.md

@@ -0,0 +1,105 @@
+# Workflows: exact call sequences
+
+Every command below is run as `devlift … --no-input -o json`; `-y` is added
+only after the user has seen the dry run and agreed. `jq` expressions show
+what to read from each result.
+
+## 0. Preflight (once per session)
+
+```
+devlift whoami --no-input -o json          # exit 2 → user must `devlift login`
+devlift applications list --no-input -o json | jq -r '.[].application_name'
+devlift environments list --app core --no-input -o json   # environments and regions for that application
+```
+
+## 1. Create a bucket / queue / table
+
+```
+devlift s3 create --name orders-archive --app core --env stage --region mumbai --versioning --no-replication --no-input        # exit 5: summary printed
+devlift s3 create --name orders-archive --app core --env stage --region mumbai --versioning --no-replication --no-input -y -o json
+# → {resource_code, queue_code, status, workflow_id | pr_url}
+devlift deployment status <workflow_id> --wait --no-input -o json
+```
+
+SQS: `--fifo|--no-fifo --dlq|--no-dlq` are required decisions; pass them.
+DynamoDB: `--partition-key ATTR [--partition-key-type S|N|B]`.
+A duplicate name exits 7; `s3 describe <name> --env stage` shows the existing one.
+
+## 2. Change a bucket or queue
+
+```
+devlift sqs update orders --env stage --dlq --max-receive-count 5 --no-input        # Field | Current | New, exit 5
+devlift sqs update orders --env stage --dlq --max-receive-count 5 --no-input -y -o json
+```
+`changed: false` with exit 0 means the values were already set. Same
+sequence as create afterwards (queue → approve → deploy).
+
+## 3. Create an EKS service
+
+```
+devlift repositories list --no-input -o json | jq -r '.[].full_name'
+devlift repositories branches Regobs/orders --no-input -o json | jq -r '.[].name'
+devlift languages list --no-input -o json
+devlift eks create --name orders --app core --env stage --region mumbai --type api \
+  --repo Regobs/orders --branch main --language go --version 1.24 --no-input -o json 2>&1   # exit 5: two tables (service, configuration with From column) on stderr
+# SHOW the Configuration table to the user and ASK: "These are the standard Go values. Apply them, or tell me what to change?"
+# a change becomes --set on the rerun, e.g. --set cpu_limit=0.5 --set hpa_enabled=true --set min_replicas=1 --set max_replicas=3
+devlift eks create … --no-input -y -o json
+# → {service_code, service_config_code, queue_code, queue_status: "draft", config}
+```
+Then tell the user it is a draft and continue with workflow 6.
+`--type worker` drops health/service_path/ALB fields (no load balancer).
+
+## 4. Change a running service's settings
+
+```
+devlift eks show orders --env stage --no-input -o json           # current values; pending_request + pending_keys if a draft exists
+devlift eks edit orders --env stage --set memory_limit=1 --no-input     # Current | New, exit 5
+devlift eks edit orders --env stage --set memory_limit=1 --no-input -y -o json
+# → {changed, changes{field:{from,to}}, queue_code, queue_status}
+```
+Exit 7 "has a submit/approved settings request": the change set is under
+review; use `request withdraw` (own) or wait for deploy/revoke.
+
+## 5. Kong routes
+
+```
+devlift kong routes list orders --env stage --no-input -o json        # groups: method, auth, tag, paths, pending
+devlift kong route add orders --env stage --method GET --auth jwt --path '~/orders/api/v1/orders$' --no-input     # exit 5
+devlift kong route add … --no-input -y -o json                         # → {changed, change{tag,method,added,…}, queue_code}
+```
+Public routes: `--auth public` (default tag `orders-open`). Existing tag with
+the other auth → exit 7: pick another `--tag`.
+
+## 6. Review lane (settings and routes move together)
+
+```
+devlift request list --service orders --env stage --no-input -o json     # what exists, statuses, you.can_approve / can_deploy
+devlift request submit orders --no-input -y -o json                      # → requests[] all "submit"; exit 7 if another author holds the lane
+devlift approval list --no-input -o json                                 # reviewer inbox
+devlift request show orders --no-input -o json                           # frozen diff for the reviewer
+devlift approval approve orders --no-input -y -o json                    # → requests[] all "approved"
+# alternatives: approval request-changes orders --comment "…" -y ; approval reject orders --comment "…" -y ; approval revoke orders -y ; request withdraw orders -y
+```
+Self-approval works only where the resource group's rule allows it (403 → exit 4 otherwise).
+
+## 7. Deploy and verify
+
+```
+devlift eks deploy orders --env stage --no-input                         # lists approved rows, exit 5
+devlift eks deploy orders --env stage --no-input -y --wait -o json       # → {workflow_id, status, state}
+devlift eks status orders --env stage --no-input -o json                 # .deployment (stages, pr_url) and .application (ArgoCD state)
+```
+Production: `--confirm-name orders` in place of relying on `-y`.
+Read `.application.state`: `up` = healthy pod; `waiting_for_argocd` /
+`starting` = keep polling (`--wait`); `not_configured` = no ArgoCD for that
+environment, only the pipeline result is available.
+
+## 8. Find things
+
+```
+devlift services list --search order --no-input -o json
+devlift deployment list --env stage --status running --no-input -o json
+devlift deployment status <workflow-id> --no-input -o json
+devlift request history orders --env stage --no-input -o json
+```

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/devlift_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlift-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: DevLift command-line tool: create, change, review and deploy DevLift resources from the terminal.
 License: Proprietary
 Keywords: devlift,devops,deployment,infrastructure,cli
@@ -40,17 +40,29 @@ the same endpoints the web dashboard uses. Nothing here talks to an LLM.
 ## Install
 
 ```
-pip install devlift-cli
+pipx install devlift-cli
 ```
 
-Or, to keep it in its own environment and off your system Python:
+pipx gives the tool its own environment and puts `devlift` and `dl` on your
+PATH. If you do not have it:
 
 ```
-pipx install devlift-cli
+sudo apt install pipx      # Debian / Ubuntu
+brew install pipx          # macOS
+pipx ensurepath            # once, then reopen your terminal
 ```
 
-Upgrade with `pip install -U devlift-cli` (or `pipx upgrade devlift-cli`).
-Your profile and sign-in live in `~/.config/devlift` and survive upgrades.
+Upgrade with `pipx upgrade devlift-cli`. Your profile and sign-in live in
+`~/.config/devlift` and survive upgrades.
+
+**Using pip instead?** Do it inside a virtual environment. A plain
+`pip install devlift-cli` fails on recent Debian, Ubuntu and Fedora with
+`externally-managed-environment`, because those systems refuse to let pip
+touch the system Python.
+
+```
+python3 -m venv ~/.venvs/devlift && ~/.venvs/devlift/bin/pip install devlift-cli
+```
 
 Then:
 
@@ -61,9 +73,9 @@ devlift whoami
 devlift man
 ```
 
-Requires Python 3.11 or newer. To remove it: `pip uninstall devlift-cli`
-(or `pipx uninstall devlift-cli`). That leaves `~/.config/devlift`, so delete
-that too if you want your profiles and sign-in gone as well.
+Requires Python 3.11 or newer. To remove it: `pipx uninstall devlift-cli`.
+That leaves `~/.config/devlift`, so delete that too if you want your profiles
+and sign-in gone as well.
 
 Several backends? `devlift profile list`, `devlift profile use <name>` and
 `devlift profile show` switch between them and say which one is active.
@@ -92,14 +104,18 @@ Variables and secrets stay in the dashboard by design.
 
 ## Claude skill
 
-`skills/devlift/` teaches Claude (Claude Code or any Agent Skills host) to
-drive this CLI non-interactively. Install with:
+A Claude skill ships inside the package, teaching Claude (Claude Code or any
+Agent Skills host) to drive this CLI non-interactively. Install it with:
 
 ```
-ln -s "$(pwd)/skills/devlift" ~/.claude/skills/devlift      # personal
-# or copy it into a project's .claude/skills/devlift
+devlift skill install              # ~/.claude/skills/devlift, every project
+devlift skill install --project    # ./.claude/skills/devlift, this repo only
 ```
 
+Start a new Claude session afterwards to pick it up. `devlift skill status`
+says where it is installed and whether it still matches the CLI;
+`devlift skill install --force` refreshes it after an upgrade.
+
 ## Development
 
 Building, testing and cutting a release: see `CONTRIBUTING.md` in the source

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/devlift_cli.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ devlift_cli/commands/manual.py
 devlift_cli/commands/repositories.py
 devlift_cli/commands/request.py
 devlift_cli/commands/s3.py
+devlift_cli/commands/skill.py
 devlift_cli/commands/sqs.py
 devlift_cli/data/placement/vance.json
 devlift_cli/ops/__init__.py
@@ -56,4 +57,8 @@ devlift_cli/render/__init__.py
 devlift_cli/render/output.py
 devlift_cli/resolve/__init__.py
 devlift_cli/resolve/allowlist.py
-devlift_cli/resolve/names.py
+devlift_cli/resolve/names.py
+devlift_cli/skill/SKILL.md
+devlift_cli/skill/reference/commands.md
+devlift_cli/skill/reference/exit-codes.md
+devlift_cli/skill/reference/workflows.md

{devlift_cli-0.1.0 → devlift_cli-0.1.2}/pyproject.toml

@@ -51,4 +51,8 @@ version = { attr = "devlift_cli.__version__" }
 include = ["devlift_cli*"]
 
 [tool.setuptools.package-data]
-devlift_cli = ["MANUAL.md", "data/placement/*.json"]
+# The skill ships inside the package on purpose: `devlift skill install` has to
+# work for someone who installed from PyPI and has no access to this private
+# repository, and shipping both in one wheel means the skill can never describe
+# a different set of commands from the CLI that carried it.
+devlift_cli = ["MANUAL.md", "skill/SKILL.md", "skill/reference/*.md", "data/placement/*.json"]