mammoth-cli 2.0.35__tar.gz → 2.0.36__tar.gz

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.35
+Version: 2.0.36
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.8,>=0.7.15
+Requires-Dist: mammoth-io<0.8,>=0.7.16
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6
@@ -207,12 +207,13 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
 `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once. Onboard me first:
 1. If `mammoth --version` fails, install, then re-check (new shell if needed):
    curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
-2. Run `mammoth auth status`. If it shows no credentials, print exactly this
-   and wait until I say done: "In the Mammoth web app open Workspace settings
-   → API Tokens → Create token, copy the key and the secret (shown once), and
-   note the workspace id (the number after /workspaces/ in the address bar),
-   then run in your own terminal: mammoth auth login" — never ask for, read, or pass a key
-   or secret yourself, and never run auth login.
+2. Run `mammoth auth status`. If it shows no credentials or a
+   `recommendation`, print exactly this and wait until I say done: "In the
+   Mammoth web app open Workspace settings → API Tokens → Create token (no
+   project, so I can create projects), copy the token (it starts with mm_ and
+   is shown once), and note the workspace id (the number after /workspaces/
+   in the address bar), then run in your own terminal: mammoth auth login" —
+   never ask for, read, or pass the token yourself, and never run auth login.
 3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
    follow the guide it prints.
 Work inside `mammoth project ensure 'PROJECT NAME'` unless I name a project;
@@ -265,7 +266,7 @@ The full generated list is in [docs/reference/commands.md](https://github.com/Ed
 |---|---|
 | [Installation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/installation.md) | Install the CLI and the agent skill. |
 | [Quick start](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/quickstart.md) | Log in and run your first commands. |
-| [Authentication](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/authentication.md) | Getting an API key, login, profiles, projects. |
+| [Authentication](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/authentication.md) | Getting an API token, login, profiles, projects. |
 | [Agent handover and operation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agents.md) | Cold start, discovery, checkpoints, recovery. |
 | [Portable handoff format](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-handoff.md) | Nonsecret checkpoint schema and receiving procedure. |
 | [Bundled agent skill](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) | Focused routing for shell-capable agents. |

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/README.md

@@ -179,12 +179,13 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
 `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once. Onboard me first:
 1. If `mammoth --version` fails, install, then re-check (new shell if needed):
    curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
-2. Run `mammoth auth status`. If it shows no credentials, print exactly this
-   and wait until I say done: "In the Mammoth web app open Workspace settings
-   → API Tokens → Create token, copy the key and the secret (shown once), and
-   note the workspace id (the number after /workspaces/ in the address bar),
-   then run in your own terminal: mammoth auth login" — never ask for, read, or pass a key
-   or secret yourself, and never run auth login.
+2. Run `mammoth auth status`. If it shows no credentials or a
+   `recommendation`, print exactly this and wait until I say done: "In the
+   Mammoth web app open Workspace settings → API Tokens → Create token (no
+   project, so I can create projects), copy the token (it starts with mm_ and
+   is shown once), and note the workspace id (the number after /workspaces/
+   in the address bar), then run in your own terminal: mammoth auth login" —
+   never ask for, read, or pass the token yourself, and never run auth login.
 3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
    follow the guide it prints.
 Work inside `mammoth project ensure 'PROJECT NAME'` unless I name a project;
@@ -237,7 +238,7 @@ The full generated list is in [docs/reference/commands.md](https://github.com/Ed
 |---|---|
 | [Installation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/installation.md) | Install the CLI and the agent skill. |
 | [Quick start](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/quickstart.md) | Log in and run your first commands. |
-| [Authentication](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/authentication.md) | Getting an API key, login, profiles, projects. |
+| [Authentication](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/authentication.md) | Getting an API token, login, profiles, projects. |
 | [Agent handover and operation](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agents.md) | Cold start, discovery, checkpoints, recovery. |
 | [Portable handoff format](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-handoff.md) | Nonsecret checkpoint schema and receiving procedure. |
 | [Bundled agent skill](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md) | Focused routing for shell-capable agents. |

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.0.35"
+__version__ = "2.0.36"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.35
+version: 2.0.36
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines, dashboards, exports, and handoffs."
 ---
 
@@ -23,7 +23,7 @@ task names it, and check `meta.profile`/`auth status` `endpoint` match the
 intended environment before doing anything. If no profile has credentials,
 tell the operator to run `mammoth auth login` in their own terminal (add
 `--profile NAME` only for a profile other than `default`; [auth](references/auth.md)
-says where the key and secret come from) and wait; never ask for a key or secret in chat,
+says where the token comes from) and wait; never ask for the token in chat,
 never read one from a file or environment variable, never run `auth login`
 yourself. If any envelope carries `meta.update_available`, run its `command`
 before the next step.

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/mammoth_cli/bundled_skill/mammoth-cli/references/auth.md

@@ -1,7 +1,16 @@
 # Authentication and profiles
 
-Required: API key, API secret, workspace id. Optional: a one-label server
-prefix (default `app`, resolving to `https://app.mammoth.io/api/v2`).
+Required: an API token (`mm_...`) and a workspace id. Optional: a one-label
+server prefix (default `app`, resolving to `https://app.mammoth.io/api/v2`).
+Login accepts nothing else. If `auth status` reports `credential: key_secret`
+(a profile saved by an older CLI), it still works, but ask the operator to run
+`mammoth auth login` again with a token.
+
+A token may be limited to one project. It then gets HTTP 403
+`authorization_required` in every other project, including a project it has
+created. When that happens, stop creating projects: ask the operator which
+project the token belongs to and pass `--project ID`, or ask for a token
+created without a project.
 
 ## Precedence
 1. Explicit login handed to the current command (secure prompt or `--input`).
@@ -13,14 +22,14 @@ history, or unrelated files for them.
 
 ## How an agent obtains credentials
 
-An agent never receives the key or secret. When `auth status` reports a
+An agent never receives the token. When `auth status` reports a
 missing profile or `has_credentials=false`, stop and hand the login to the
 human operator:
 
 1. Tell the operator where the credentials come from: in the Mammoth web app,
-   **Workspace settings → API Tokens → Create token** gives a key and a secret;
-   the web app shows the secret only once (on an existing token, **Generate new
-   secret** replaces it). The workspace id is the number after `/workspaces/`
+   **Workspace settings → API Tokens → Create token** gives a token that
+   starts with `mm_`; the web app shows it only once (if it is lost, create a
+   new one). The workspace id is the number after `/workspaces/`
    in the web app's address bar. Then give the exact command to run in
    **their own** terminal. For production it is:
 
@@ -30,9 +39,9 @@ human operator:
 
    Add `--server-prefix release` only when the task names the release
    environment, and `--profile NAME` only when the operator wants a profile
-   other than `default`. The command prompts for the key and secret with
-   hidden input, then the workspace id, so no secret enters chat, argv, or
-   history. Credentials are per environment: a release key never
+   other than `default`. The command prompts for the token with hidden
+   input, then the workspace id, so no secret enters chat, argv, or history.
+   Tokens are per environment and per workspace: a release token never
    authenticates on `app`.
    On macOS the Keychain may show a dialog about `mammoth-cli`; tell the
    operator to choose **Always Allow**. If the keychain cannot be used (for
@@ -41,12 +50,11 @@ human operator:
 2. Wait for the operator to confirm, then re-run
    `mammoth auth status --profile PROFILE` and
    `mammoth doctor --profile PROFILE`.
-3. Do not ask the operator to paste the key or secret into chat. Do not run
+3. Do not ask the operator to paste the token into chat. Do not run
    `auth login` yourself, with or without `--input`, unless the operator has
    explicitly given you a protected `0600` credential file path to use.
 
-The only supported configuration is the API key, API secret, workspace id, and
-an optional one-label server prefix (default `app`). There is no base-url
+The only supported configuration is the API token, the workspace id, and an optional one-label server prefix (default `app`). There is no base-url
 override.
 
 ## Cold-start sequence
@@ -107,8 +115,7 @@ authorization failure. When using the selected profile, `--profile PROFILE`
 may be omitted.
 
 For an ordinary human-operated terminal, prefer the first command: it asks
-for the key and secret without putting either in shell history, argv, chat, or
-logs. For headless POSIX work, create the JSON file outside the repository, set
+for the token without putting it in shell history, argv, chat, or logs. For headless POSIX work, create the JSON file outside the repository, set
 its permissions to `0600`, and pass only its path. With a protected POSIX file,
 specify `--storage file` explicitly; `--storage auto` can require an available
 OS keyring and is not a reliable headless fallback. On Windows, do not use the
@@ -116,8 +123,8 @@ file backend as a secret store; use the OS keyring or stop and obtain a
 supported secure store. Remove any input file after the
 profile is stored.
 
-`creds.json` is a `0600` JSON file: `{"api_key": "...", "api_secret": "...",
-"workspace_id": 4, "server_prefix": "app"}` (`server_prefix` optional). You can
+`creds.json` is a `0600` JSON file: `{"api_token": "mm_...", "workspace_id": 4,
+"server_prefix": "app"}` (`server_prefix` optional). You can
 also pipe it with `--input - --input-format json`.
 
 Secrets live in the OS keyring (or an explicitly selected `0600` file

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/mammoth_cli/bundled_skill/mammoth-cli/references/handoff.md

@@ -24,7 +24,7 @@ workspace/project scope. Then add:
 - completed actions and remaining objectives;
 - a cleanup owner plus dependency order.
 
-Never include API keys, API secrets, tokens, headers, credentials files, raw
+Never include API tokens, headers, credentials files, raw
 secret-bearing input, or unredacted response bodies. IDs and display names are
 safe only when needed to identify the authorized task.
 

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/mammoth_cli/commands/auth.py

@@ -1,11 +1,10 @@
 """Bespoke `auth` command family: login, status, logout.
 
-Authentication has exactly three required inputs (API key, API secret,
-workspace id) and one optional input (server prefix, default ``app``).
-Authentication always requires a login; there is no environment credential
-path. These commands never accept a secret as an ordinary command-line value:
-the API key and secret come from a hidden TTY prompt or a permission-checked
-JSON/YAML login document read through the shared ``--input`` option.
+Authentication needs an API token (``mm_...``, sent as ``Authorization:
+Bearer``) and a workspace id, plus an optional server prefix (default
+``app``). There is no environment credential path. These commands never accept a secret as an
+ordinary command-line value: it comes from a hidden TTY prompt or a
+permission-checked JSON/YAML login document read through ``--input``.
 """
 
 from __future__ import annotations
@@ -128,6 +127,11 @@ def _validate_login_document(document: dict[str, Any]) -> LoginRequest:
             code="invalid_login_document",
             message="The login request document failed validation.",
             exit_status=EXIT_USAGE,
+            hint=(
+                'Expected {"api_token": "mm_...", "workspace_id": N} with an optional '
+                '"server_prefix". API key + secret pairs are no longer accepted; create '
+                "a token in Workspace settings -> API Tokens."
+            ),
             details={"errors": errors},
         ) from exc
 
@@ -160,6 +164,38 @@ def _prompt_secret(label: str) -> str:
     return str(value)
 
 
+TOKEN_PREFIX = "mm_"  # noqa: S105 - a public prefix, not a credential
+# A token is ``mm_`` + 43 url-safe characters. Its public id (``app_key``) is
+# ``mm_`` + 16 hex characters and cannot authenticate: catch that paste early.
+_APP_KEY_LENGTH = 19
+
+
+def _check_token_shape(token: str) -> None:
+    """Reject a value that cannot be an API token before any network call."""
+    if not token.startswith(TOKEN_PREFIX):
+        raise CliError(
+            code="invalid_credentials",
+            message="That is not a Mammoth API token (tokens start with mm_).",
+            exit_status=EXIT_USAGE,
+            hint=(
+                "Create a token in Workspace settings -> API Tokens and paste the value "
+                "shown once (mm_ followed by about 43 characters). API key + secret "
+                "pairs are no longer accepted at login."
+            ),
+        )
+    if len(token) <= _APP_KEY_LENGTH:
+        raise CliError(
+            code="invalid_credentials",
+            message="That looks like the token's id (app key), not the token.",
+            exit_status=EXIT_USAGE,
+            hint=(
+                "Use the token shown once when it was created (mm_ followed by about "
+                "43 characters). If it is lost, create a new token in Workspace "
+                "settings -> API Tokens."
+            ),
+        )
+
+
 def _prompt_blockers(invocation: Invocation) -> list[str]:
     """Reasons this invocation cannot interactively prompt, in report order.
 
@@ -208,15 +244,16 @@ def _run_login(
         document = load_input_document(invocation.input_file, invocation.input_format)
         assert document is not None
         request = _validate_login_document(document)
-        api_key, api_secret = request.api_key, request.api_secret
+        api_token = request.api_token.strip()
+        _check_token_shape(api_token)
         effective_workspace = request.workspace_id
         effective_prefix = server_prefix if server_prefix is not None else request.server_prefix
     elif not blockers:
-        # Two flows, nothing else: a terminal prompts for everything (key,
-        # secret, then workspace id), and non-interactive uses --input. The
-        # workspace is asked last, after the credentials.
-        api_key = _prompt_secret("API key")
-        api_secret = _prompt_secret("API secret")
+        # Two flows, nothing else: a terminal prompts for everything (token,
+        # then workspace id), and non-interactive uses --input. The workspace
+        # is asked last, after the credential.
+        api_token = _prompt_secret("API token")
+        _check_token_shape(api_token)
         effective_workspace = typer.prompt("Workspace id", type=int)
         effective_prefix = server_prefix
     else:
@@ -238,20 +275,14 @@ def _run_login(
             message="A positive --workspace id is required.",
             exit_status=EXIT_USAGE,
         )
-    if not api_key or not api_secret:
-        raise CliError(
-            code="invalid_credentials",
-            message="The API key and secret must be non-empty.",
-            exit_status=EXIT_USAGE,
-        )
-
     resolved_base_url = resolve_base_url(effective_prefix)
 
     resolved_auth = ResolvedAuth(
-        api_key=api_key,
-        api_secret=api_secret,
+        api_key=None,
+        api_secret=None,
         workspace_id=effective_workspace,
         base_url=resolved_base_url,
+        api_token=api_token,
     )
     service = service_factory.build_service(resolved_auth, timeout=invocation.timeout)
     try:
@@ -266,20 +297,17 @@ def _run_login(
                 **exc.details,
                 "endpoint_base_url": resolved_base_url,
                 "workspace_id": effective_workspace,
-                # Receipts only (length and last four characters). The output
-                # layer redacts any key that looks like a credential, so these
-                # are named for what they are: descriptions, not values.
-                "credential_receipt": {
-                    "key": _masked_receipt(api_key),
-                    "second_value_length": len(api_secret),
-                },
+                # A receipt only (length and last four characters). The output
+                # layer redacts any key that looks like a credential, so this
+                # is named for what it is: a description, not the value.
+                "credential_receipt": {"type": "api token", "shape": _masked_receipt(api_token)},
             }
             exc.hint = (
-                f"{resolved_base_url} rejected this key/secret for workspace "
-                f"{effective_workspace}. Credentials are per environment: a key issued on "
-                "one Mammoth server does not authenticate on another. Check the key, the "
-                "secret, the workspace id, and that --server-prefix matches where the key "
-                "was issued."
+                f"{resolved_base_url} rejected this token for workspace "
+                f"{effective_workspace}. Credentials are per environment and per workspace: "
+                "a token issued on one Mammoth server or workspace does not authenticate on "
+                "another. Check the token, the workspace id, and that --server-prefix "
+                "matches where it was issued."
             )
         raise
     finally:
@@ -300,10 +328,9 @@ def _run_login(
     profiles.save_profile(record, select=True)
     storage_used = credentials.store_credentials(
         profile_name,
-        api_key,
-        api_secret,
         storage=cast(credentials.StorageMode, storage),
         interactive=not blockers,
+        api_token=api_token,
     )
 
     data = {
@@ -311,6 +338,7 @@ def _run_login(
         "workspace_id": effective_workspace,
         "base_url": resolved_base_url,
         "storage": storage_used,
+        "credential": "token",
     }
     return data, {"profile": profile_name, "workspace_id": effective_workspace}
 
@@ -337,8 +365,9 @@ def auth_login(
 ) -> None:
     """Log in and store one profile's credentials.
 
-    Prompts for the API key and secret in a terminal. For non-interactive use
-    (agents, CI), pass ``--input FILE`` with a login document instead.
+    Prompts for the API token (mm_..., from Workspace settings -> API Tokens)
+    and the workspace id in a terminal. For non-interactive use (agents, CI), pass
+    ``--input FILE`` with {"api_token": ..., "workspace_id": ...} instead.
     Performs a lightweight connection check before saving anything; a failed
     check leaves existing profile state unchanged.
     """
@@ -382,7 +411,8 @@ def _run_status(invocation: Invocation, *, check: bool) -> tuple[dict[str, Any],
     """Report local (or, with `--check`, live) authentication state."""
     profile_name = invocation.profile or profiles.get_selected()
     record = profiles.get_profile(profile_name)
-    has_creds = credentials.has_credentials(profile_name)
+    credential = credentials.load_credential(profile_name)
+    has_creds = credential is not None
 
     if record is not None:
         endpoint = resolve_base_url(record.server_prefix)
@@ -396,9 +426,15 @@ def _run_status(invocation: Invocation, *, check: bool) -> tuple[dict[str, Any],
         "workspace_id": workspace_id,
         "endpoint": endpoint,
         "has_credentials": has_creds,
+        "credential": credential.kind if credential is not None else None,
         "checked": False,
         "connected": None,
     }
+    if credential is not None and credential.kind == "key_secret":
+        data["recommendation"] = (
+            "This profile uses a legacy API key + secret. Create an API token in "
+            "Workspace settings -> API Tokens and run 'mammoth auth login' again."
+        )
 
     if check:
         auth = resolve_auth(invocation)

{mammoth_cli-2.0.35 → mammoth_cli-2.0.36}/mammoth_cli/commands/doctor.py

@@ -214,18 +214,19 @@ def doctor(invocation: Invocation) -> HandlerResult:
         )
     )
     keyring_error: str | None = None
+    legacy_credential = False
     try:
-        creds_present = credentials.has_credentials(profile_name)
+        stored = credentials.load_credential(profile_name)
+        creds_present = stored is not None
+        legacy_credential = stored is not None and stored.kind == "key_secret"
     except CliError as error:
         creds_present = False
         keyring_error = error.code
-    checks.append(
-        _check(
-            "credentials",
-            creds_present,
-            keyring_error or ("credentials present" if creds_present else "none stored"),
-        )
-    )
+    if legacy_credential:
+        creds_detail = "legacy API key + secret stored; log in again with an API token"
+    else:
+        creds_detail = "api token present" if creds_present else "none stored"
+    checks.append(_check("credentials", creds_present, keyring_error or creds_detail))
 
     endpoint_detail = "unresolved"
     auth_ok = False
@@ -303,7 +304,7 @@ def doctor(invocation: Invocation) -> HandlerResult:
         )
 
     recommendations: list[str] = []
-    if record is None or not creds_present:
+    if record is None or not creds_present or legacy_credential:
         login_profile = f" --profile {shlex.quote(profile_name)}" if profile_name else ""
         login_storage = " --storage file" if keyring_error else ""
         recommendations.append(f"mammoth auth login{login_profile}{login_storage}")