feat: file system support for ls, mkdir, rm, push, pull and get app path

README.md

@@ -36,6 +36,7 @@ A universal command-line tool for managing iOS and Android devices, simulators,
 - **Screencapture video streaming**: Stream mjpeg/h264 video directly from device
 - **Device Control**: Reboot devices, tap screen coordinates, press hardware buttons
 - **App Management**: Launch, terminate, install, uninstall, list, and get foreground apps
+- **Filesystem**: Push, pull, list, mkdir, and rm files on-device or in app containers (Android, iOS Simulator)
 - **Crash Reports**: List and fetch crash reports from iOS and Android devices
 
 ### 🎯 Platform Support
@@ -221,6 +222,88 @@ Example output for `apps foreground`:
 }
 ```
 
+### Filesystem 📂
+
+Access files on the device or inside an app's data container. Currently supported on **Android** and **iOS Simulator**.
+
+```bash
+# Get the data container path of an app (Android)
+mobilecli apps path <bundle-id> --device <device-id>
+
+# List files at any absolute path (defaults to device root if omitted)
+mobilecli fs ls --device <device-id>
+mobilecli fs ls --device <device-id> /sdcard
+mobilecli fs ls --device <device-id> /sdcard/Download
+
+# List files inside an app's data container
+mobilecli fs ls --device <device-id> com.example.app
+mobilecli fs ls --device <device-id> com.example.app /Documents
+
+# Pull a file from the device to local disk
+mobilecli fs pull --device <device-id> /sdcard/recording.mp4 ./recording.mp4
+
+# Pull a file from an app's private container
+mobilecli fs pull --device <device-id> /data/user/0/com.example.app/files/db.sqlite ./db.sqlite
+
+# Push a file to the device
+mobilecli fs push --device <device-id> ./config.json /sdcard/config.json
+
+# Push a file into an app's private container
+mobilecli fs push --device <device-id> ./config.json /data/user/0/com.example.app/files/config.json
+
+# Create a directory
+mobilecli fs mkdir --device <device-id> /sdcard/myfolder
+
+# Create a directory and all parent directories
+mobilecli fs mkdir --device <device-id> -p /sdcard/a/b/c
+mobilecli fs mkdir --device <device-id> -p /data/user/0/com.example.app/files/cache/v2
+
+# Remove a file
+mobilecli fs rm --device <device-id> /sdcard/old_file.txt
+
+# Remove a directory recursively
+mobilecli fs rm --device <device-id> -r /sdcard/myfolder
+mobilecli fs rm --device <device-id> -r /data/user/0/com.example.app/files/cache
+```
+
+Example output for `apps path`:
+```json
+{
+  "status": "ok",
+  "data": {
+    "path": "/data/user/0/com.example.app"
+  }
+}
+```
+
+Example output for `fs ls`:
+```json
+{
+  "status": "ok",
+  "data": [
+    {
+      "name": "files",
+      "path": "/data/user/0/com.example.app/files",
+      "size": 4096,
+      "modTime": "2026-05-11T19:20:00Z",
+      "isDir": true
+    },
+    {
+      "name": "shared_prefs",
+      "path": "/data/user/0/com.example.app/shared_prefs",
+      "size": 4096,
+      "modTime": "2026-05-11T12:49:00Z",
+      "isDir": true
+    }
+  ]
+}
+```
+
+**Notes:**
+- Paths under `/data/user/` are accessed via `run-as`, so the app must be debuggable.
+- Pushing to `/data/user/` stages the file through `/data/local/tmp/` then copies it into the container.
+- Pulling binary files (images, databases, DEX files) is fully supported and binary-safe on all platforms.
+
 ### Agent Management 🤖
 
 On **iOS**, the on-device agent is required for touch input (taps, swipes, button presses), screen capture streaming, and UI tree inspection. These capabilities are not available through standard iOS tooling without an agent running on the device.

cli/apps.go

@@ -132,6 +132,25 @@ var appsUninstallCmd = &cobra.Command{
 	},
 }
 
+var appsPathCmd = &cobra.Command{
+	Use:   "path [bundle_id]",
+	Short: "Get the container path of an app on a device",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		req := commands.AppPathRequest{
+			DeviceID: deviceId,
+			BundleID: args[0],
+		}
+
+		response := commands.AppPathCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+		return nil
+	},
+}
+
 var appsForegroundCmd = &cobra.Command{
 	Use:   "foreground",
 	Short: "Get the currently foreground app on a device",
@@ -159,6 +178,7 @@ func init() {
 	appsCmd.AddCommand(appsInstallCmd)
 	appsCmd.AddCommand(appsUninstallCmd)
 	appsCmd.AddCommand(appsForegroundCmd)
+	appsCmd.AddCommand(appsPathCmd)
 
 	appsLaunchCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to launch app on")
 	appsLaunchCmd.Flags().StringVar(&locale, "locale", "", "Comma-separated BCP 47 locale tags (e.g., fr-FR,en-GB)")
@@ -170,4 +190,5 @@ func init() {
 	appsInstallCmd.Flags().StringVar(&signingIdentity, "signing-identity", "", "Signing identity name to use for re-signing")
 	appsUninstallCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to uninstall app from")
 	appsForegroundCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to get foreground app from")
+	appsPathCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device")
 }

cli/fs.go

@@ -0,0 +1,156 @@
+package cli
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mobile-next/mobilecli/commands"
+	"github.com/spf13/cobra"
+)
+
+var fsCmd = &cobra.Command{
+	Use:   "fs",
+	Short: "Access device filesystem",
+	Long:  `Push, pull, list, and manage files on a device or in an app's container.`,
+}
+
+var fsPushCmd = &cobra.Command{
+	Use:   "push <local-path> <remote-path>",
+	Short: "Push a file to the device or into an app's container",
+	Args:  cobra.ExactArgs(2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		req := commands.FsPushRequest{
+			DeviceID:   deviceId,
+			LocalPath:  args[0],
+			RemotePath: args[1],
+		}
+		response := commands.FsPushCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+		return nil
+	},
+}
+
+var fsPullCmd = &cobra.Command{
+	Use:   "pull <remote-path> <local-path>",
+	Short: "Pull a file from the device or from an app's container",
+	Args:  cobra.ExactArgs(2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		req := commands.FsPullRequest{
+			DeviceID:   deviceId,
+			RemotePath: args[0],
+			LocalPath:  args[1],
+		}
+		response := commands.FsPullCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+		return nil
+	},
+}
+
+var fsLsCmd = &cobra.Command{
+	Use:   "ls [bundle-id] [remote-path]",
+	Short: "List files on the device or in an app's container",
+	Args:  cobra.RangeArgs(0, 2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		var bundleID, remotePath string
+		switch len(args) {
+		case 1:
+			if strings.HasPrefix(args[0], "/") {
+				remotePath = args[0]
+			} else {
+				bundleID = args[0]
+			}
+		case 2:
+			bundleID = args[0]
+			remotePath = args[1]
+		}
+		req := commands.FsListRequest{
+			DeviceID:   deviceId,
+			BundleID:   bundleID,
+			RemotePath: remotePath,
+		}
+		response := commands.FsListCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+		return nil
+	},
+}
+
+var (
+	fsMkdirParents bool
+	fsRmRecursive  bool
+)
+
+var fsMkdirCmd = &cobra.Command{
+	Use:   "mkdir [bundle-id] <remote-path>",
+	Short: "Create a directory on the device or in an app's container",
+	Args:  cobra.RangeArgs(1, 2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		var bundleID, remotePath string
+		if len(args) == 1 {
+			remotePath = args[0]
+		} else {
+			bundleID = args[0]
+			remotePath = args[1]
+		}
+		req := commands.FsMkdirRequest{
+			DeviceID:   deviceId,
+			BundleID:   bundleID,
+			RemotePath: remotePath,
+			Parents:    fsMkdirParents,
+		}
+		response := commands.FsMkdirCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+		return nil
+	},
+}
+
+var fsRmCmd = &cobra.Command{
+	Use:   "rm [bundle-id] <remote-path>",
+	Short: "Remove a file or directory on the device or in an app's container",
+	Args:  cobra.RangeArgs(1, 2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		var bundleID, remotePath string
+		if len(args) == 1 {
+			remotePath = args[0]
+		} else {
+			bundleID = args[0]
+			remotePath = args[1]
+		}
+		req := commands.FsRmRequest{
+			DeviceID:   deviceId,
+			BundleID:   bundleID,
+			RemotePath: remotePath,
+			Recursive:  fsRmRecursive,
+		}
+		response := commands.FsRmCommand(req)
+		printJson(response)
+		if response.Status == "error" {
+			return fmt.Errorf("%s", response.Error)
+		}
+		return nil
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(fsCmd)
+
+	fsCmd.AddCommand(fsPushCmd)
+	fsCmd.AddCommand(fsPullCmd)
+	fsCmd.AddCommand(fsLsCmd)
+	fsCmd.AddCommand(fsMkdirCmd)
+	fsCmd.AddCommand(fsRmCmd)
+
+	fsMkdirCmd.Flags().BoolVarP(&fsMkdirParents, "parents", "p", false, "Create parent directories as needed")
+	fsRmCmd.Flags().BoolVarP(&fsRmRecursive, "recursive", "r", false, "Remove directories and their contents recursively")
+}

cli/root.go

@@ -121,6 +121,25 @@ REMOTE DEVICES:
   # Release an allocated remote device
   mobilecli remote release --device <device-id>
 
+FILESYSTEM:
+  # List files on the device
+  mobilecli fs ls --device <device-id> /sdcard
+
+  # List files in an app's container
+  mobilecli fs ls --device <device-id> com.example.app /Documents
+
+  # Pull a file from the device
+  mobilecli fs pull --device <device-id> /sdcard/file.txt ./file.txt
+
+  # Push a file to the device
+  mobilecli fs push --device <device-id> ./file.txt /sdcard/file.txt
+
+  # Create a directory
+  mobilecli fs mkdir --device <device-id> -p /sdcard/a/b/c
+
+  # Remove a file or directory
+  mobilecli fs rm --device <device-id> -r /sdcard/myfolder
+
 UTILITIES:
   # Open a URL or deep link
   mobilecli url --device <device-id> https://example.com

commands/apps.go

@@ -155,6 +155,31 @@ func InstallAppCommand(req InstallAppRequest) *CommandResponse {
 	})
 }
 
+type AppPathRequest struct {
+	DeviceID string `json:"deviceId"`
+	BundleID string `json:"bundleId"`
+}
+
+func AppPathCommand(req AppPathRequest) *CommandResponse {
+	if req.BundleID == "" {
+		return NewErrorResponse(fmt.Errorf("bundle ID is required"))
+	}
+
+	device, err := FindDeviceOrAutoSelect(req.DeviceID)
+	if err != nil {
+		return NewErrorResponse(fmt.Errorf("error finding device: %w", err))
+	}
+
+	path, err := device.GetAppContainerPath(req.BundleID)
+	if err != nil {
+		return NewErrorResponse(fmt.Errorf("failed to get app path on device %s: %w", device.ID(), err))
+	}
+
+	return NewSuccessResponse(map[string]any{
+		"path": path,
+	})
+}
+
 type UninstallAppRequest struct {
 	DeviceID    string `json:"deviceId"`
 	PackageName string `json:"packageName"`