feat(cli): add --app flag to host-targeted commands

Adds --app <name> to status, stats, log, lock, unlock, maintenance on/off,
start, stop, restart, env set/get/list/unset, and accessory list. With
--app + --host these commands resolve the target app from server-side
state instead of requiring a teploy.yml in the cwd — the same pattern
rollback --app already used.

Motivation: teploy-dash shells out to the CLI for these actions but has
no app directory on disk. Previously it could only pass --host, so the
CLI fell back to config.LoadApp(".") and either failed or acted on the
wrong app. Now dash can target any {server, app} pair.

New shared resolveApp(ctx, flags, appName) helper in connect.go unifies
the two resolution paths:
  - appName == "": load teploy.yml from cwd, connect to its server
  - appName != "": require --host, read deploy state from server (no
    teploy.yml needed); Domain is enriched from state for commands that
    need it (maintenance)

Notes:
- maintenance keeps its 'requires Caddy-managed ingress' guard only on
  the cwd path — server state doesn't record ingress mode, so --app
  assumes default Caddy ingress.
- accessory stop/start/logs/upgrade/backup/restore still need accessory
  config from teploy.yml and remain cwd-bound; only 'accessory list'
  (read-only) gained --app.

Verified end-to-end on a live VM: status/env/lock/unlock/restart/log
--app all work from a directory with no teploy.yml; the --host-required
guard fires cleanly. Unit tests cover the guard + the no-config error.

Author: im-tyler

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to teploy are documented here. Format follows [Keep a Change
 ## [Unreleased]
 
 ### Added
+- `--app <name>` flag on `status`, `stats`, `log`, `lock`, `unlock`, `maintenance on/off`, `start`, `stop`, `restart`, `env set/get/list/unset`, and `accessory list`. With `--app` + `--host`, these commands act on a deployed app by reading server-side state instead of requiring a `teploy.yml` in the working directory — the same model `rollback --app` already used. This is what lets teploy-dash (and any automation without an app checkout) drive these commands for arbitrary apps. A shared `resolveApp` helper unifies the cwd-`teploy.yml` path and the `--app`+`--host` path. `maintenance` keeps its Caddy-ingress guard only on the cwd path (server state doesn't record ingress mode); the accessory subcommands that need accessory config from `teploy.yml` (stop/start/logs/upgrade/backup/restore) remain cwd-bound, only `accessory list` gained `--app`.
 - `keep_versions: N` — auto-prune older app versions on deploy. The current and immediately-previous versions are always protected; older versions beyond `N` are removed (containers + images). Container-deploy only — static deploys use `keep_releases`. Default `0` = keep everything (legacy behavior).
 - `healthcheck.<proc>.disable` — per-process override that passes `--no-healthcheck` to `docker run`. Useful for worker containers that share an image with a web container and would otherwise inherit a useless HTTP healthcheck.
 - `ingress: external` — opt out of Caddy entirely. The container still joins the `teploy` Docker network with its app-name alias, but Teploy doesn't write or reload the Caddyfile. For users fronting the app with Cloudflare Tunnel, Tailscale Funnel, nginx, AWS ALB, or any other external ingress.

internal/cli/accessory.go

@@ -49,26 +49,28 @@ func newAccessoryCmd(flags *Flags) *cobra.Command {
 }
 
 func newAccessoryListCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List accessory containers",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runAccessoryList(flags)
+			return runAccessoryList(flags, appName)
 		},
 	}
+	// `list` only needs the app name (read-only container listing), so it
+	// supports --app for use outside an app directory (e.g. teploy-dash).
+	// The other accessory subcommands need accessory config from teploy.yml
+	// and remain cwd-bound.
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
-func runAccessoryList(flags *Flags) error {
-	appCfg, err := loadAppCfgForAccessory()
-	if err != nil {
-		return err
-	}
-
+func runAccessoryList(flags *Flags, appName string) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	executor, err := connectForApp(ctx, flags, appCfg)
+	appCfg, executor, err := resolveApp(ctx, flags, appName)
 	if err != nil {
 		return err
 	}

internal/cli/connect.go

@@ -7,8 +7,59 @@ import (
 
 	"github.com/useteploy/teploy/internal/config"
 	"github.com/useteploy/teploy/internal/ssh"
+	"github.com/useteploy/teploy/internal/state"
 )
 
+// resolveApp returns the app config plus an open SSH connection for a command
+// that operates on a single app. It unifies the two ways a command can be told
+// which app + server to act on:
+//
+//   - Without --app (appName == ""): load teploy.yml from the cwd and connect
+//     to the app's configured server. This is the normal interactive path.
+//   - With --app (appName != ""): require --host and read the deployed state
+//     from the server — no teploy.yml needed. This is the path teploy-dash and
+//     other automation use, where there is no app directory on disk.
+//
+// In the --app path the returned AppConfig is minimal: App + Server are always
+// set, and Domain is enriched from server-side state when available (commands
+// like maintenance need it). Fields that only live in teploy.yml (e.g. custom
+// Ingress) are not recoverable from server state, so --app assumes the default
+// Caddy-managed ingress; commands that depend on non-default ingress should be
+// run from an app directory.
+//
+// The caller owns the returned executor and must Close it.
+func resolveApp(ctx context.Context, flags *Flags, appName string) (*config.AppConfig, ssh.Executor, error) {
+	if appName == "" {
+		appCfg, err := config.LoadApp(".")
+		if err != nil {
+			return nil, nil, err
+		}
+		ex, err := connectForApp(ctx, flags, appCfg)
+		if err != nil {
+			return nil, nil, err
+		}
+		return appCfg, ex, nil
+	}
+
+	if flags.Host == "" {
+		return nil, nil, fmt.Errorf("--host is required when using --app")
+	}
+	host, user, key, err := config.ResolveServer(flags.Host, flags.Host, flags.User, flags.Key)
+	if err != nil {
+		return nil, nil, err
+	}
+	fmt.Printf("Connecting to %s@%s...\n", user, host)
+	ex, err := ssh.Connect(ctx, ssh.ConnectConfig{Host: host, User: user, KeyPath: key})
+	if err != nil {
+		return nil, nil, err
+	}
+	appCfg := &config.AppConfig{App: appName, Server: flags.Host}
+	if st, err := state.Read(ctx, ex, appName); err == nil && st != nil {
+		appCfg.Domain = st.Domain
+	}
+	return appCfg, ex, nil
+}
+
 // connectForApp resolves the server from app config and establishes an SSH connection.
 // Uses the first server from appCfg.Servers if Server is empty.
 func connectForApp(ctx context.Context, flags *Flags, appCfg *config.AppConfig) (ssh.Executor, error) {

internal/cli/connect_test.go

@@ -0,0 +1,32 @@
+package cli
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// resolveApp's --app path requires --host. The guard must fire BEFORE any SSH
+// connection attempt, so this is pure-logic testable without a live server.
+// (The happy --app path does a real SSH connect + state.Read and is covered by
+// end-to-end smoke tests against a live VM, not unit tests.)
+func TestResolveApp_AppWithoutHostErrors(t *testing.T) {
+	_, _, err := resolveApp(context.Background(), &Flags{}, "myapp")
+	if err == nil {
+		t.Fatal("expected error when --app is set without --host")
+	}
+	if !strings.Contains(err.Error(), "--host is required") {
+		t.Errorf("error = %q, want it to mention --host is required", err.Error())
+	}
+}
+
+// With no --app and no teploy.yml in the cwd, resolveApp should surface the
+// config-load error (not panic, not silently succeed). t.Chdir to a temp dir
+// guarantees there's no teploy.yml to accidentally pick up.
+func TestResolveApp_NoAppNoConfigErrors(t *testing.T) {
+	t.Chdir(t.TempDir())
+	_, _, err := resolveApp(context.Background(), &Flags{}, "")
+	if err == nil {
+		t.Fatal("expected error when no --app and no teploy.yml present")
+	}
+}

internal/cli/env.go

@@ -27,7 +27,8 @@ func newEnvCmd(flags *Flags) *cobra.Command {
 }
 
 func newEnvSetCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "set KEY=value [KEY=value...]",
 		Short: "Set one or more environment variables",
 		Args:  cobra.MinimumNArgs(1),
@@ -40,21 +41,18 @@ func newEnvSetCmd(flags *Flags) *cobra.Command {
 				}
 				pairs[arg[:idx]] = arg[idx+1:]
 			}
-			return runEnvSet(flags, pairs)
+			return runEnvSet(flags, appName, pairs)
 		},
 	}
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
-func runEnvSet(flags *Flags, pairs map[string]string) error {
-	appCfg, err := config.LoadApp(".")
-	if err != nil {
-		return err
-	}
-
+func runEnvSet(flags *Flags, appName string, pairs map[string]string) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	executor, err := connectForApp(ctx, flags, appCfg)
+	appCfg, executor, err := resolveApp(ctx, flags, appName)
 	if err != nil {
 		return err
 	}
@@ -72,26 +70,24 @@ func runEnvSet(flags *Flags, pairs map[string]string) error {
 }
 
 func newEnvGetCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "get KEY",
 		Short: "Get the value of an environment variable",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runEnvGet(flags, args[0])
+			return runEnvGet(flags, appName, args[0])
 		},
 	}
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
-func runEnvGet(flags *Flags, key string) error {
-	appCfg, err := config.LoadApp(".")
-	if err != nil {
-		return err
-	}
-
+func runEnvGet(flags *Flags, appName, key string) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	executor, err := connectForApp(ctx, flags, appCfg)
+	appCfg, executor, err := resolveApp(ctx, flags, appName)
 	if err != nil {
 		return err
 	}
@@ -110,30 +106,27 @@ func runEnvGet(flags *Flags, key string) error {
 func newEnvListCmd(flags *Flags) *cobra.Command {
 	var reveal bool
 
+	var appName string
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List all environment variables",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runEnvList(flags, reveal)
+			return runEnvList(flags, appName, reveal)
 		},
 	}
 
 	cmd.Flags().BoolVar(&reveal, "reveal", false, "show values instead of masking them")
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
 
 	return cmd
 }
 
-func runEnvList(flags *Flags, reveal bool) error {
-	appCfg, err := config.LoadApp(".")
-	if err != nil {
-		return err
-	}
-
+func runEnvList(flags *Flags, appName string, reveal bool) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	executor, err := connectForApp(ctx, flags, appCfg)
+	appCfg, executor, err := resolveApp(ctx, flags, appName)
 	if err != nil {
 		return err
 	}
@@ -161,26 +154,24 @@ func runEnvList(flags *Flags, reveal bool) error {
 }
 
 func newEnvUnsetCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "unset KEY",
 		Short: "Remove an environment variable",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runEnvUnset(flags, args[0])
+			return runEnvUnset(flags, appName, args[0])
 		},
 	}
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
-func runEnvUnset(flags *Flags, key string) error {
-	appCfg, err := config.LoadApp(".")
-	if err != nil {
-		return err
-	}
-
+func runEnvUnset(flags *Flags, appName, key string) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	executor, err := connectForApp(ctx, flags, appCfg)
+	appCfg, executor, err := resolveApp(ctx, flags, appName)
 	if err != nil {
 		return err
 	}

internal/cli/lifecycle.go

@@ -7,54 +7,57 @@ import (
 	"os/signal"
 
 	"github.com/spf13/cobra"
-	"github.com/useteploy/teploy/internal/config"
 	"github.com/useteploy/teploy/internal/deploy"
 	"github.com/useteploy/teploy/internal/notify"
 )
 
 func newStopCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "stop",
 		Short: "Stop all containers for the app",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runLifecycle(flags, "stop")
+			return runLifecycle(flags, appName, "stop")
 		},
 	}
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
 func newStartCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "start",
 		Short: "Start all stopped containers for the app",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runLifecycle(flags, "start")
+			return runLifecycle(flags, appName, "start")
 		},
 	}
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
 func newRestartCmd(flags *Flags) *cobra.Command {
-	return &cobra.Command{
+	var appName string
+	cmd := &cobra.Command{
 		Use:   "restart",
 		Short: "Restart all containers for the app",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runLifecycle(flags, "restart")
+			return runLifecycle(flags, appName, "restart")
 		},
 	}
+	cmd.Flags().StringVar(&appName, "app", "", "app name — act on server state instead of teploy.yml (requires --host)")
+	return cmd
 }
 
-func runLifecycle(flags *Flags, action string) error {
-	appCfg, err := config.LoadApp(".")
-	if err != nil {
-		return err
-	}
-
+func runLifecycle(flags *Flags, appName, action string) error {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
-	executor, err := connectForApp(ctx, flags, appCfg)
+	appCfg, executor, err := resolveApp(ctx, flags, appName)
 	if err != nil {
 		return err
 	}