Add workspace flag to CLI args

README.md

@@ -43,6 +43,8 @@ These examples are production-ready and include best practices for each platform
 
 ## Monorepo Workspace Support
 
+> **Note:** If you're looking to associate a scan with a named Socket workspace (e.g. because your repo is identified as `org/repo`), see the [`--workspace` flag](#repository) instead. The `--workspace-name` flag described in this section is an unrelated monorepo feature.
+
 The Socket CLI supports scanning specific workspaces within monorepo structures while preserving git context from the repository root. This is useful for organizations that maintain multiple applications or services in a single repository.
 
 ### Key Features
@@ -114,7 +116,7 @@ This will simultaneously generate:
 ## Usage
 
 ```` shell
-socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}]
+socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--workspace WORKSPACE] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}]
           [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]]
           [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]
           [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME]
@@ -138,14 +140,21 @@ If you don't want to provide the Socket API Token every time then you can use th
 | --api-token | False    |         | Socket Security API token (can also be set via SOCKET_SECURITY_API_TOKEN env var) |
 
 #### Repository
-| Parameter        | Required | Default | Description                                                             |
-|:-----------------|:---------|:--------|:------------------------------------------------------------------------|
-| --repo           | False    | *auto*  | Repository name in owner/repo format (auto-detected from git remote)   |
-| --repo-is-public | False    | False   | If set, flags a new repository creation as public. Defaults to false.   |
-| --integration    | False    | api     | Integration type (api, github, gitlab, azure, bitbucket)                |
-| --owner          | False    |         | Name of the integration owner, defaults to the socket organization slug |
-| --branch         | False    | *auto*  | Branch name (auto-detected from git)                                   |
-| --committers     | False    | *auto*  | Committer(s) to filter by (auto-detected from git commit)              |
+| Parameter        | Required | Default | Description                                                                                                       |
+|:-----------------|:---------|:--------|:------------------------------------------------------------------------------------------------------------------|
+| --repo           | False    | *auto*  | Repository name in owner/repo format (auto-detected from git remote)                                             |
+| --workspace      | False    |         | The Socket workspace to associate the scan with (e.g. `my-org` in `my-org/my-repo`). See note below.           |
+| --repo-is-public | False    | False   | If set, flags a new repository creation as public. Defaults to false.                                            |
+| --integration    | False    | api     | Integration type (api, github, gitlab, azure, bitbucket)                                                         |
+| --owner          | False    |         | Name of the integration owner, defaults to the socket organization slug                                          |
+| --branch         | False    | *auto*  | Branch name (auto-detected from git)                                                                             |
+| --committers     | False    | *auto*  | Committer(s) to filter by (auto-detected from git commit)                                                        |
+
+> **`--workspace` vs `--workspace-name`** — these are two distinct flags for different purposes:
+>
+> - **`--workspace <string>`** maps to the Socket API's `workspace` query parameter on `CreateOrgFullScan`. Use it when your repository belongs to a named Socket workspace (e.g. an org with multiple workspace groups). Example: `--repo my-repo --workspace my-org`. Without this flag, scans are created without workspace context and may not appear under the correct workspace in the Socket dashboard.
+>
+> - **`--workspace-name <string>`** is a monorepo feature. It appends a suffix to the repository slug to create a unique name in Socket (e.g. `my-repo-frontend`). It must always be paired with `--sub-path` and has nothing to do with the API `workspace` field. See [Monorepo Workspace Support](#monorepo-workspace-support) below.
 
 #### Pull Request and Commit
 | Parameter        | Required | Default | Description                                    |

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.72"
+version = "2.2.73"
 requires-python = ">= 3.10"
 license = {"file" = "LICENSE"}
 dependencies = [

socketsecurity/__init__.py

@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.2.72'
+__version__ = '2.2.73'
 USER_AGENT = f'SocketPythonCLI/{__version__}'

socketsecurity/config.py

@@ -66,6 +66,7 @@ class CliConfig:
     save_manifest_tar: Optional[str] = None
     sub_paths: List[str] = field(default_factory=list)
     workspace_name: Optional[str] = None
+    workspace: Optional[str] = None
     # Reachability Flags
     reach: bool = False
     reach_version: Optional[str] = None
@@ -144,6 +145,7 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             'save_manifest_tar': args.save_manifest_tar,
             'sub_paths': args.sub_paths or [],
             'workspace_name': args.workspace_name,
+            'workspace': args.workspace,
             'slack_webhook': args.slack_webhook,
             'reach': args.reach,
             'reach_version': args.reach_version,
@@ -254,6 +256,12 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help="Repository name in owner/repo format",
         required=False
     )
+    repo_group.add_argument(
+        "--workspace",
+        metavar="<string>",
+        help="The workspace of the repository to associate the full-scan with.",
+        required=False
+    )
     repo_group.add_argument(
         "--repo-is-public",
         dest="repo_is_public",

socketsecurity/socketcli.py

@@ -464,7 +464,8 @@ def main_code():
         make_default_branch=is_default_branch,
         set_as_pending_head=is_default_branch,
         tmp=False,
-        scan_type='socket_tier1' if config.reach else 'socket'
+        scan_type='socket_tier1' if config.reach else 'socket',
+        workspace=config.workspace or None,
     )
 
     params.include_license_details = not config.exclude_license_details

tests/unit/test_cli_config.py

@@ -60,4 +60,25 @@ def test_strict_blocking_with_disable_blocking(self):
             "--disable-blocking"
         ])
         assert config.strict_blocking is True
-        assert config.disable_blocking is True
+        assert config.disable_blocking is True
+
+    def test_workspace_flag(self):
+        """Test that --workspace is parsed and stored correctly."""
+        config = CliConfig.from_args(["--api-token", "test", "--workspace", "my-workspace"])
+        assert config.workspace == "my-workspace"
+
+    def test_workspace_default_is_none(self):
+        """Test that workspace defaults to None when not supplied."""
+        config = CliConfig.from_args(["--api-token", "test"])
+        assert config.workspace is None
+
+    def test_workspace_is_independent_of_workspace_name(self):
+        """--workspace and --workspace-name are distinct flags with distinct purposes."""
+        config = CliConfig.from_args([
+            "--api-token", "test",
+            "--workspace", "my-workspace",
+            "--sub-path", ".",
+            "--workspace-name", "monorepo-suffix",
+        ])
+        assert config.workspace == "my-workspace"
+        assert config.workspace_name == "monorepo-suffix"