hereya-cli 0.63.0 → 0.64.1

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g hereya-cli
 $ hereya COMMAND
 running command...
 $ hereya (--version)
-hereya-cli/0.63.0 linux-x64 node-v24.13.0
+hereya-cli/0.64.1 linux-x64 node-v24.13.1
 $ hereya --help [COMMAND]
 USAGE
   $ hereya COMMAND
@@ -38,10 +38,12 @@ USAGE
 * [`hereya delete-state`](#hereya-delete-state)
 * [`hereya deploy`](#hereya-deploy)
 * [`hereya doc PACKAGE`](#hereya-doc-package)
+* [`hereya docker run IMAGE`](#hereya-docker-run-image)
 * [`hereya down`](#hereya-down)
 * [`hereya env [NAME]`](#hereya-env-name)
 * [`hereya env set [NAME]`](#hereya-env-set-name)
 * [`hereya flow add PACKAGE`](#hereya-flow-add-package)
+* [`hereya flow docker run IMAGE`](#hereya-flow-docker-run-image)
 * [`hereya flow down`](#hereya-flow-down)
 * [`hereya flow env [NAME]`](#hereya-flow-env-name)
 * [`hereya flow provid PACKAGE`](#hereya-flow-provid-package)
@@ -103,7 +105,7 @@ EXAMPLES
   $ hereya add cloudy/docker_postgres
 ```
 
-_See code: [src/commands/add/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/add/index.ts)_
+_See code: [src/commands/add/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/add/index.ts)_
 
 ## `hereya bootstrap INFRASTRUCTURETYPE`
 
@@ -128,7 +130,7 @@ EXAMPLES
   $ hereya bootstrap local
 ```
 
-_See code: [src/commands/bootstrap/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/bootstrap/index.ts)_
+_See code: [src/commands/bootstrap/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/bootstrap/index.ts)_
 
 ## `hereya config export-backend [FILE]`
 
@@ -150,7 +152,7 @@ EXAMPLES
   $ hereya config export-backend ./path/to/export.json
 ```
 
-_See code: [src/commands/config/export-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/config/export-backend/index.ts)_
+_See code: [src/commands/config/export-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/config/export-backend/index.ts)_
 
 ## `hereya config get-backend`
 
@@ -167,7 +169,7 @@ EXAMPLES
   $ hereya config get-backend
 ```
 
-_See code: [src/commands/config/get-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/config/get-backend/index.ts)_
+_See code: [src/commands/config/get-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/config/get-backend/index.ts)_
 
 ## `hereya config import-backend FILE`
 
@@ -187,7 +189,7 @@ EXAMPLES
   $ hereya config import-backend ./path/to/cloud-backend.json
 ```
 
-_See code: [src/commands/config/import-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/config/import-backend/index.ts)_
+_See code: [src/commands/config/import-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/config/import-backend/index.ts)_
 
 ## `hereya config use-backend TYPE`
 
@@ -209,7 +211,7 @@ EXAMPLES
   $ hereya config use-backend local
 ```
 
-_See code: [src/commands/config/use-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/config/use-backend/index.ts)_
+_See code: [src/commands/config/use-backend/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/config/use-backend/index.ts)_
 
 ## `hereya delete-state`
 
@@ -235,7 +237,7 @@ EXAMPLES
   $ hereya delete-state --workspace staging
 ```
 
-_See code: [src/commands/delete-state/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/delete-state/index.ts)_
+_See code: [src/commands/delete-state/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/delete-state/index.ts)_
 
 ## `hereya deploy`
 
@@ -260,7 +262,7 @@ EXAMPLES
   $ hereya deploy
 ```
 
-_See code: [src/commands/deploy/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/deploy/index.ts)_
+_See code: [src/commands/deploy/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/deploy/index.ts)_
 
 ## `hereya doc PACKAGE`
 
@@ -293,7 +295,38 @@ EXAMPLES
   $ hereya doc my-package --no-doc
 ```
 
-_See code: [src/commands/doc/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/doc/index.ts)_
+_See code: [src/commands/doc/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/doc/index.ts)_
+
+## `hereya docker run IMAGE`
+
+Run a Docker container with hereya env vars injected as -e flags.
+
+```
+USAGE
+  $ hereya docker run IMAGE... [--chdir <value>] [-p <value>] [-w <value>]
+
+ARGUMENTS
+  IMAGE...  Docker image to run
+
+FLAGS
+  -p, --port=<value>       [default: 8080] port to forward and set as PORT env var (default: 8080)
+  -w, --workspace=<value>  name of the workspace to use
+      --chdir=<value>      directory to run command in
+
+DESCRIPTION
+  Run a Docker container with hereya env vars injected as -e flags.
+
+EXAMPLES
+  $ hereya docker run myapp:latest
+
+  $ hereya docker run -w staging myapp:latest
+
+  $ hereya docker run -p 3000 myapp:latest
+
+  $ hereya docker run myapp:latest -- --rm -v ./data:/data
+```
+
+_See code: [src/commands/docker/run/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/docker/run/index.ts)_
 
 ## `hereya down`
 
@@ -320,7 +353,7 @@ EXAMPLES
   $ hereya down
 ```
 
-_See code: [src/commands/down/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/down/index.ts)_
+_See code: [src/commands/down/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/down/index.ts)_
 
 ## `hereya env [NAME]`
 
@@ -351,7 +384,7 @@ EXAMPLES
   $ hereya env -w dev -l
 ```
 
-_See code: [src/commands/env/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/env/index.ts)_
+_See code: [src/commands/env/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/env/index.ts)_
 
 ## `hereya env set [NAME]`
 
@@ -378,7 +411,7 @@ EXAMPLES
   $ hereya env set FOO -v bar -w dev
 ```
 
-_See code: [src/commands/env/set/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/env/set/index.ts)_
+_See code: [src/commands/env/set/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/env/set/index.ts)_
 
 ## `hereya flow add PACKAGE`
 
@@ -416,7 +449,37 @@ EXAMPLES
   $ hereya flow add cloudy/docker_postgres -p DB_NAME=mydb -p DB_USER=admin
 ```
 
-_See code: [src/commands/flow/add/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/add/index.ts)_
+_See code: [src/commands/flow/add/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/add/index.ts)_
+
+## `hereya flow docker run IMAGE`
+
+Run a Docker container with hereya env vars in a git branch-based workspace
+
+```
+USAGE
+  $ hereya flow docker run IMAGE... [--chdir <value>] [--pin] [-p <value>] [--profile <value>]
+
+ARGUMENTS
+  IMAGE...  Docker image to run
+
+FLAGS
+  -p, --port=<value>     [default: 8080] port to forward and set as PORT env var (default: 8080)
+      --chdir=<value>    directory to run command in
+      --pin              append git commit SHA to workspace name for commit-specific isolation
+      --profile=<value>  profile to use for the workspace (will be appended to workspace name)
+
+DESCRIPTION
+  Run a Docker container with hereya env vars in a git branch-based workspace
+
+EXAMPLES
+  $ hereya flow docker run myapp:latest
+
+  $ hereya flow docker run --profile staging myapp:latest
+
+  $ hereya flow docker run --pin myapp:latest -- --rm
+```
+
+_See code: [src/commands/flow/docker/run/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/docker/run/index.ts)_
 
 ## `hereya flow down`
 
@@ -450,7 +513,7 @@ EXAMPLES
   $ hereya flow down --pin
 ```
 
-_See code: [src/commands/flow/down/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/down/index.ts)_
+_See code: [src/commands/flow/down/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/down/index.ts)_
 
 ## `hereya flow env [NAME]`
 
@@ -484,7 +547,7 @@ EXAMPLES
   $ hereya flow env -l
 ```
 
-_See code: [src/commands/flow/env/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/env/index.ts)_
+_See code: [src/commands/flow/env/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/env/index.ts)_
 
 ## `hereya flow provid PACKAGE`
 
@@ -513,7 +576,7 @@ EXAMPLES
   $ hereya flow provid hereya/postgres --pin
 ```
 
-_See code: [src/commands/flow/provid/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/provid/index.ts)_
+_See code: [src/commands/flow/provid/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/provid/index.ts)_
 
 ## `hereya flow remove PACKAGE`
 
@@ -543,7 +606,7 @@ EXAMPLES
   $ hereya flow remove cloudy/docker_postgres --profile staging
 ```
 
-_See code: [src/commands/flow/remove/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/remove/index.ts)_
+_See code: [src/commands/flow/remove/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/remove/index.ts)_
 
 ## `hereya flow run CMD`
 
@@ -572,7 +635,7 @@ EXAMPLES
   $ hereya flow run --pin -- npm test
 ```
 
-_See code: [src/commands/flow/run/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/run/index.ts)_
+_See code: [src/commands/flow/run/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/run/index.ts)_
 
 ## `hereya flow up`
 
@@ -606,7 +669,7 @@ EXAMPLES
   $ hereya flow up --pin
 ```
 
-_See code: [src/commands/flow/up/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/flow/up/index.ts)_
+_See code: [src/commands/flow/up/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/flow/up/index.ts)_
 
 ## `hereya help [COMMAND]`
 
@@ -663,7 +726,7 @@ EXAMPLES
   $ hereya import org/my-package -f state.tfstate -w my-workspace
 ```
 
-_See code: [src/commands/import/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/import/index.ts)_
+_See code: [src/commands/import/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/import/index.ts)_
 
 ## `hereya init PROJECT`
 
@@ -689,7 +752,7 @@ EXAMPLES
   $ hereya init myProject -w=defaultWorkspace --chdir=./myProject
 ```
 
-_See code: [src/commands/init/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/init/index.ts)_
+_See code: [src/commands/init/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/init/index.ts)_
 
 ## `hereya login [URL]`
 
@@ -718,7 +781,7 @@ EXAMPLES
   $ hereya login --token=your-token https://cloud.hereya.dev
 ```
 
-_See code: [src/commands/login/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/login/index.ts)_
+_See code: [src/commands/login/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/login/index.ts)_
 
 ## `hereya logout`
 
@@ -735,7 +798,7 @@ EXAMPLES
   $ hereya logout
 ```
 
-_See code: [src/commands/logout/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/logout/index.ts)_
+_See code: [src/commands/logout/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/logout/index.ts)_
 
 ## `hereya provid PACKAGE`
 
@@ -763,7 +826,7 @@ EXAMPLES
   $ hereya provid hereya/postgres --workspace staging
 ```
 
-_See code: [src/commands/provid/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/provid/index.ts)_
+_See code: [src/commands/provid/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/provid/index.ts)_
 
 ## `hereya publish`
 
@@ -786,7 +849,7 @@ EXAMPLES
   $ hereya publish --chdir=/path/to/package
 ```
 
-_See code: [src/commands/publish/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/publish/index.ts)_
+_See code: [src/commands/publish/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/publish/index.ts)_
 
 ## `hereya remove PACKAGE`
 
@@ -814,7 +877,7 @@ EXAMPLES
   $ hereya remove cloudy/docker_postgres
 ```
 
-_See code: [src/commands/remove/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/remove/index.ts)_
+_See code: [src/commands/remove/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/remove/index.ts)_
 
 ## `hereya run CMD`
 
@@ -840,7 +903,7 @@ EXAMPLES
   $ hereya run -w uat -- node index.js
 ```
 
-_See code: [src/commands/run/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/run/index.ts)_
+_See code: [src/commands/run/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/run/index.ts)_
 
 ## `hereya search QUERY`
 
@@ -871,7 +934,7 @@ EXAMPLES
   $ hereya search database --json
 ```
 
-_See code: [src/commands/search/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/search/index.ts)_
+_See code: [src/commands/search/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/search/index.ts)_
 
 ## `hereya unbootstrap INFRASTRUCTURETYPE`
 
@@ -896,7 +959,7 @@ EXAMPLES
   $ hereya unbootstrap local
 ```
 
-_See code: [src/commands/unbootstrap/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/unbootstrap/index.ts)_
+_See code: [src/commands/unbootstrap/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/unbootstrap/index.ts)_
 
 ## `hereya undeploy`
 
@@ -921,7 +984,7 @@ EXAMPLES
   $ hereya undeploy
 ```
 
-_See code: [src/commands/undeploy/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/undeploy/index.ts)_
+_See code: [src/commands/undeploy/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/undeploy/index.ts)_
 
 ## `hereya up`
 
@@ -948,7 +1011,7 @@ EXAMPLES
   $ hereya up
 ```
 
-_See code: [src/commands/up/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/up/index.ts)_
+_See code: [src/commands/up/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/up/index.ts)_
 
 ## `hereya workspace create NAME`
 
@@ -973,7 +1036,7 @@ EXAMPLES
   $ hereya workspace create dev
 ```
 
-_See code: [src/commands/workspace/create/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/create/index.ts)_
+_See code: [src/commands/workspace/create/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/create/index.ts)_
 
 ## `hereya workspace delete NAME`
 
@@ -993,7 +1056,7 @@ EXAMPLES
   $ hereya workspace delete dev
 ```
 
-_See code: [src/commands/workspace/delete/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/delete/index.ts)_
+_See code: [src/commands/workspace/delete/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/delete/index.ts)_
 
 ## `hereya workspace env [NAME]`
 
@@ -1019,7 +1082,7 @@ EXAMPLES
   $ hereya workspace env myEnv -w dev
 ```
 
-_See code: [src/commands/workspace/env/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/env/index.ts)_
+_See code: [src/commands/workspace/env/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/env/index.ts)_
 
 ## `hereya workspace env set`
 
@@ -1043,7 +1106,7 @@ EXAMPLES
   $ hereya workspace env set -w my-workspace -n myVar -v my-value -i aws -s
 ```
 
-_See code: [src/commands/workspace/env/set/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/env/set/index.ts)_
+_See code: [src/commands/workspace/env/set/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/env/set/index.ts)_
 
 ## `hereya workspace env unset`
 
@@ -1064,7 +1127,7 @@ EXAMPLES
   $ hereya workspace env unset -w my-workspace -n myVar
 ```
 
-_See code: [src/commands/workspace/env/unset/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/env/unset/index.ts)_
+_See code: [src/commands/workspace/env/unset/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/env/unset/index.ts)_
 
 ## `hereya workspace install PACKAGE`
 
@@ -1091,7 +1154,7 @@ EXAMPLES
   $ hereya workspace install hereya/aws-cognito
 ```
 
-_See code: [src/commands/workspace/install/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/install/index.ts)_
+_See code: [src/commands/workspace/install/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/install/index.ts)_
 
 ## `hereya workspace list`
 
@@ -1115,7 +1178,7 @@ EXAMPLES
   $ hereya workspace list --org personal
 ```
 
-_See code: [src/commands/workspace/list/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/list/index.ts)_
+_See code: [src/commands/workspace/list/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/list/index.ts)_
 
 ## `hereya workspace set-profile PROFILE`
 
@@ -1139,7 +1202,7 @@ EXAMPLES
   $ hereya workspace set-profile prod-profile -w production
 ```
 
-_See code: [src/commands/workspace/set-profile/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/set-profile/index.ts)_
+_See code: [src/commands/workspace/set-profile/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/set-profile/index.ts)_
 
 ## `hereya workspace uninstall PACKAGE`
 
@@ -1166,5 +1229,5 @@ EXAMPLES
   $ hereya workspace uninstall hereya/aws-cognito
 ```
 
-_See code: [src/commands/workspace/uninstall/index.ts](https://github.com/hereya/hereya-cli/blob/v0.63.0/src/commands/workspace/uninstall/index.ts)_
+_See code: [src/commands/workspace/uninstall/index.ts](https://github.com/hereya/hereya-cli/blob/v0.64.1/src/commands/workspace/uninstall/index.ts)_
 <!-- commandsstop -->

package/dist/backend/cloud/cloud-backend.js

@@ -12,6 +12,9 @@ export class CloudBackend {
         if (input.parameters) {
             formData.append('parameters', JSON.stringify(input.parameters));
         }
+        if (input.version) {
+            formData.append('version', input.version);
+        }
         const response = await fetch(`${this.config.url}/api/workspaces/${encodeURIComponent(input.workspace)}/packages`, {
             body: formData,
             headers: {

package/dist/backend/common.d.ts

@@ -75,6 +75,7 @@ export type AddPackageToWorkspaceInput = {
     parameters?: {
         [key: string]: string;
     };
+    version?: string;
     workspace: string;
 };
 export type AddPackageToWorkspaceOutput = {

package/dist/backend/file.js

@@ -33,7 +33,7 @@ export class FileBackend {
             ...workspace.packages,
             [input.package]: {
                 parameters: input.parameters,
-                version: '',
+                version: input.version || '',
             },
         };
         const newEnv = Object.fromEntries(Object.entries(input.env).map(([key, value]) => [key, `${input.infra}:${value}`]));

package/dist/commands/docker/run/index.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class DockerRun extends Command {
+    static args: {
+        image: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        chdir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/docker/run/index.js

@@ -0,0 +1,111 @@
+import { Args, Command, Flags } from '@oclif/core';
+import spawn from 'cross-spawn';
+import { getBackend } from '../../../backend/index.js';
+import { ensureDockerNetwork } from '../../../infrastructure/local.js';
+import { getConfigManager } from '../../../lib/config/index.js';
+import { getEnvManager } from '../../../lib/env/index.js';
+import { getProfileFromWorkspace } from '../../../lib/profile-utils.js';
+import { runShell } from '../../../lib/shell.js';
+import { validateDevelopmentWorkspace } from '../../../lib/workspace-validation.js';
+export default class DockerRun extends Command {
+    static args = {
+        image: Args.string({ description: 'Docker image to run', required: true }),
+    };
+    static description = 'Run a Docker container with hereya env vars injected as -e flags.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> myapp:latest',
+        '<%= config.bin %> <%= command.id %> -w staging myapp:latest',
+        '<%= config.bin %> <%= command.id %> -p 3000 myapp:latest',
+        '<%= config.bin %> <%= command.id %> myapp:latest -- --rm -v ./data:/data',
+    ];
+    static flags = {
+        chdir: Flags.string({
+            description: 'directory to run command in',
+            required: false,
+        }),
+        port: Flags.integer({
+            char: 'p',
+            default: 8080,
+            description: 'port to forward and set as PORT env var (default: 8080)',
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'name of the workspace to use',
+            required: false,
+        }),
+    };
+    static strict = false;
+    async run() {
+        const { args, argv, flags } = await this.parse(DockerRun);
+        const projectRootDir = flags.chdir || process.env.HEREYA_PROJECT_ROOT_DIR;
+        const configManager = getConfigManager();
+        const loadConfigOutput = await configManager.loadConfig({ projectRootDir });
+        if (!loadConfigOutput.found) {
+            this.warn(`Project not initialized. Run 'hereya init' first.`);
+            return;
+        }
+        const { config } = loadConfigOutput;
+        let { workspace } = flags;
+        if (!workspace) {
+            workspace = config.workspace;
+        }
+        if (!workspace) {
+            this.error('you must specify a workspace to run the command in');
+        }
+        const backend = await getBackend();
+        const validation = await validateDevelopmentWorkspace(workspace, backend, 'docker run', config.project);
+        if (!validation.isValid) {
+            this.error(validation.message);
+        }
+        const profile = await getProfileFromWorkspace(backend, workspace, config.project);
+        const envManager = getEnvManager();
+        const getProjectEnvOutput = await envManager.getProjectEnv({
+            profile,
+            projectRootDir,
+            workspace,
+        });
+        if (!getProjectEnvOutput.success) {
+            this.error(getProjectEnvOutput.reason);
+        }
+        const { env } = getProjectEnvOutput;
+        // Apply HEREYA_DOCKER_ overrides: strip prefix and override the base key
+        const dockerPrefix = 'HEREYA_DOCKER_';
+        for (const key of Object.keys(env)) {
+            if (key.startsWith(dockerPrefix)) {
+                const targetKey = key.slice(dockerPrefix.length);
+                env[targetKey] = env[key];
+                delete env[key];
+            }
+        }
+        // Determine port: existing PORT from env takes precedence, otherwise use --port flag
+        const port = env.PORT || String(flags.port);
+        env.PORT = port;
+        const { image } = args;
+        // Build -e flags from env
+        const envFlags = [];
+        for (const [key, value] of Object.entries(env)) {
+            envFlags.push('-e', `${key}=${value}`);
+        }
+        // Extra args after -- go before the image as docker run flags
+        const extraArgs = argv.slice(1);
+        // Ensure hereya docker network exists and attach container to it
+        const networkName = await ensureDockerNetwork(runShell);
+        // docker run --network <net> -p <port>:<port> [extraArgs] -e K=V ... <image>
+        const dockerArgs = ['--network', networkName, '-p', `${port}:${port}`, ...extraArgs, ...envFlags, image];
+        this.log(`Running docker container "${image}" with ${Object.keys(env).length} env var(s) on port ${port}...`);
+        // Use spawn directly without shell to avoid special characters in env values
+        // being interpreted by /bin/sh (e.g. parentheses, brackets, semicolons)
+        const exitCode = await new Promise((resolve, reject) => {
+            const child = spawn('docker', ['run', ...dockerArgs], {
+                cwd: projectRootDir,
+                stdio: 'inherit',
+            });
+            child.on('error', reject);
+            child.on('close', (code) => resolve(code));
+        });
+        if (exitCode !== 0) {
+            this.error(`Docker run failed with exit code ${exitCode}`);
+        }
+    }
+}

package/dist/commands/flow/docker/run/index.d.ts

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+export default class FlowDockerRun extends Command {
+    static args: {
+        image: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        chdir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        pin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/flow/docker/run/index.js

@@ -0,0 +1,67 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { getBackend } from '../../../../backend/index.js';
+import { getConfigManager } from '../../../../lib/config/index.js';
+import { buildFlowWorkspaceName } from '../../../../lib/flow-utils.js';
+import { validateFlowCommand } from '../../../../lib/workspace-validation.js';
+import DockerRun from '../../../docker/run/index.js';
+export default class FlowDockerRun extends Command {
+    static args = {
+        image: Args.string({ description: 'Docker image to run', required: true }),
+    };
+    static description = 'Run a Docker container with hereya env vars in a git branch-based workspace';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> myapp:latest',
+        '<%= config.bin %> <%= command.id %> --profile staging myapp:latest',
+        '<%= config.bin %> <%= command.id %> --pin myapp:latest -- --rm',
+    ];
+    static flags = {
+        chdir: Flags.string({
+            description: 'directory to run command in',
+            required: false,
+        }),
+        pin: Flags.boolean({
+            description: 'append git commit SHA to workspace name for commit-specific isolation',
+            required: false,
+        }),
+        port: Flags.integer({
+            char: 'p',
+            default: 8080,
+            description: 'port to forward and set as PORT env var (default: 8080)',
+            required: false,
+        }),
+        profile: Flags.string({
+            description: 'profile to use for the workspace (will be appended to workspace name)',
+            required: false,
+        }),
+    };
+    static strict = false;
+    async run() {
+        const { argv, flags } = await this.parse(FlowDockerRun);
+        const projectRootDir = flags.chdir || process.env.HEREYA_PROJECT_ROOT_DIR;
+        const configManager = getConfigManager();
+        const loadConfigOutput = await configManager.loadConfig({ projectRootDir });
+        if (!loadConfigOutput.found) {
+            this.error("Project not initialized. Run 'hereya init' first.");
+        }
+        const workspaceName = await buildFlowWorkspaceName({
+            pin: flags.pin,
+            profile: flags.profile,
+            project: loadConfigOutput.config.project,
+            projectRootDir,
+        });
+        const backend = await getBackend();
+        const validation = await validateFlowCommand(workspaceName, backend);
+        if (!validation.isValid) {
+            this.error(validation.message);
+        }
+        const dockerRunArgs = ['--workspace', workspaceName];
+        if (flags.chdir)
+            dockerRunArgs.push('--chdir', flags.chdir);
+        if (flags.port !== 8080)
+            dockerRunArgs.push('--port', String(flags.port));
+        // Add all arguments (image and extra args after --)
+        const allArgs = argv;
+        dockerRunArgs.push('--', ...allArgs);
+        await DockerRun.run(dockerRunArgs);
+    }
+}

package/dist/commands/workspace/install/index.js

@@ -108,6 +108,7 @@ export default class WorkspaceInstall extends Command {
                                     infra: metadata.infra,
                                     package: ctx.provisionOutput.pkgName,
                                     parameters: ctx.parameters,
+                                    version: ctx.provisionOutput.version,
                                     workspace: flags.workspace,
                                 });
                                 if (!output.success) {

package/dist/infrastructure/local.d.ts

@@ -1,3 +1,5 @@
+import { Logger } from '../lib/log.js';
+import { runShell } from '../lib/shell.js';
 import { DeployInput, DeployOutput, Infrastructure, ProvisionInput, ProvisionOutput, SaveEnvInput, SaveEnvOutput, StoreEnvInput, StoreEnvOutput, UndeployInput, UndeployOutput, UnstoreEnvInput, UnstoreEnvOutput, UploadStateFileInput, UploadStateFileOutput } from './common.js';
 export declare class LocalInfrastructure implements Infrastructure {
     bootstrap(): Promise<void>;
@@ -15,4 +17,6 @@ export declare class LocalInfrastructure implements Infrastructure {
     undeploy(input: UndeployInput): Promise<UndeployOutput>;
     unstoreEnv(_: UnstoreEnvInput): Promise<UnstoreEnvOutput>;
     uploadStateFile(_: UploadStateFileInput): Promise<UploadStateFileOutput>;
+    private ensureDockerNetwork;
 }
+export declare function ensureDockerNetwork(shellFn: typeof runShell, logger?: Logger): Promise<string>;

package/dist/infrastructure/local.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { getIac } from '../iac/index.js';
 import { downloadPackage } from '../lib/package/index.js';
+import { runShell } from '../lib/shell.js';
 import { getPackageDownloadPath, } from './common.js';
 export class LocalInfrastructure {
     async bootstrap() {
@@ -17,6 +18,8 @@ export class LocalInfrastructure {
         return this.provision(input);
     }
     async destroy(input) {
+        const networkName = process.env.HEREYA_DOCKER_NETWORK || 'hereya-docker-network';
+        input.parameters = { ...input.parameters, hereyaDockerNetwork: networkName };
         const destPath = await getPackageDownloadPath({ id: input.id, version: input.version });
         const downloadPath = await downloadPackage(input.pkgUrl, destPath);
         const iac$ = getIac({ type: input.iacType });
@@ -42,6 +45,8 @@ export class LocalInfrastructure {
         return { env: output.env, success: true };
     }
     async provision(input) {
+        const hereyaDockerNetwork = await this.ensureDockerNetwork(input.logger);
+        input.parameters = { ...input.parameters, hereyaDockerNetwork };
         const destPath = await getPackageDownloadPath({ id: input.id, version: input.version });
         const downloadPath = await downloadPackage(input.pkgUrl, destPath);
         const iac$ = getIac({ type: input.iacType });
@@ -91,4 +96,23 @@ export class LocalInfrastructure {
     uploadStateFile(_) {
         throw new Error(`Uploading state file is not supported for local infrastructure`);
     }
+    async ensureDockerNetwork(logger) {
+        return ensureDockerNetwork(runShell, logger);
+    }
+}
+export async function ensureDockerNetwork(shellFn, logger) {
+    const networkName = process.env.HEREYA_DOCKER_NETWORK || 'hereya-docker-network';
+    try {
+        await shellFn('docker', ['network', 'inspect', networkName], { logger });
+    }
+    catch {
+        try {
+            await shellFn('docker', ['network', 'create', networkName], { logger });
+        }
+        catch {
+            // Network was likely created by a concurrent call; verify it exists
+            await shellFn('docker', ['network', 'inspect', networkName], { logger });
+        }
+    }
+    return networkName;
 }

package/dist/lib/package/index.js

@@ -94,7 +94,8 @@ function parsePackageSpec(spec) {
         return { packageName: spec };
     }
     const [, packageName, version] = match;
-    return { packageName, version };
+    // Treat "latest" as no specific version - it's not a valid git tag
+    return { packageName, version: version === 'latest' ? undefined : version };
 }
 // Helper function to try cloud resolution
 async function tryCloudResolution(input) {

package/oclif.manifest.json

@@ -1082,6 +1082,68 @@
         "index.js"
       ]
     },
+    "docker:run": {
+      "aliases": [],
+      "args": {
+        "image": {
+          "description": "Docker image to run",
+          "name": "image",
+          "required": true
+        }
+      },
+      "description": "Run a Docker container with hereya env vars injected as -e flags.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> myapp:latest",
+        "<%= config.bin %> <%= command.id %> -w staging myapp:latest",
+        "<%= config.bin %> <%= command.id %> -p 3000 myapp:latest",
+        "<%= config.bin %> <%= command.id %> myapp:latest -- --rm -v ./data:/data"
+      ],
+      "flags": {
+        "chdir": {
+          "description": "directory to run command in",
+          "name": "chdir",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "port": {
+          "char": "p",
+          "description": "port to forward and set as PORT env var (default: 8080)",
+          "name": "port",
+          "required": false,
+          "default": 8080,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workspace": {
+          "char": "w",
+          "description": "name of the workspace to use",
+          "name": "workspace",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "docker:run",
+      "pluginAlias": "hereya-cli",
+      "pluginName": "hereya-cli",
+      "pluginType": "core",
+      "strict": false,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "docker",
+        "run",
+        "index.js"
+      ]
+    },
     "env:set": {
       "aliases": [],
       "args": {
@@ -1941,6 +2003,74 @@
         "index.js"
       ]
     },
+    "flow:docker:run": {
+      "aliases": [],
+      "args": {
+        "image": {
+          "description": "Docker image to run",
+          "name": "image",
+          "required": true
+        }
+      },
+      "description": "Run a Docker container with hereya env vars in a git branch-based workspace",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> myapp:latest",
+        "<%= config.bin %> <%= command.id %> --profile staging myapp:latest",
+        "<%= config.bin %> <%= command.id %> --pin myapp:latest -- --rm"
+      ],
+      "flags": {
+        "chdir": {
+          "description": "directory to run command in",
+          "name": "chdir",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "pin": {
+          "description": "append git commit SHA to workspace name for commit-specific isolation",
+          "name": "pin",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "port": {
+          "char": "p",
+          "description": "port to forward and set as PORT env var (default: 8080)",
+          "name": "port",
+          "required": false,
+          "default": 8080,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "profile to use for the workspace (will be appended to workspace name)",
+          "name": "profile",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "flow:docker:run",
+      "pluginAlias": "hereya-cli",
+      "pluginName": "hereya-cli",
+      "pluginType": "core",
+      "strict": false,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "flow",
+        "docker",
+        "run",
+        "index.js"
+      ]
+    },
     "workspace:env:set": {
       "aliases": [],
       "args": {},
@@ -2057,5 +2187,5 @@
       ]
     }
   },
-  "version": "0.63.0"
+  "version": "0.64.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hereya-cli",
   "description": "Infrastructure as Package",
-  "version": "0.63.0",
+  "version": "0.64.1",
   "author": "Hereya Developers",
   "bin": {
     "hereya": "./bin/run.js"
@@ -20,6 +20,7 @@
     "@oclif/plugin-help": "^6.2.25",
     "@oclif/plugin-plugins": "^5.4.31",
     "chalk": "^5.5.0",
+    "cross-spawn": "^7.0.6",
     "glob": "^11.0.1",
     "ignore": "^7.0.3",
     "keytar": "^7.9.0",
@@ -37,6 +38,7 @@
     "@oclif/prettier-config": "^0.2.1",
     "@oclif/test": "^4.1.9",
     "@types/chai": "^5.0.1",
+    "@types/cross-spawn": "^6.0.6",
     "@types/jsonwebtoken": "^9.0.9",
     "@types/marked-terminal": "^6.1.1",
     "@types/mocha": "^10.0.10",