Inspect and retrieve files from your running app

Read and export files from approved .NET app directories to investigate logs, caches, and other local data.

FileSystem tools help you inspect the files behind a problem and retrieve them for closer analysis. Start with read-only access to approved directories; enable file changes only when a local debugging workflow needs them.

Work with app files

Once the app is connected and FileSystem tools are registered, use these commands to find, read, download, or upload a file. If the tools are not enabled yet, follow Install and Register the Suite below.

Find a file

With a connected session ID, list the app’s data directory:

ansight app call <session-id> files.list_directory \
  --arguments '{"root":"appData","path":"."}'

If you need the session ID or want to inspect tool availability first, use:

ansight session list --connected --json
ansight app tools <session-id> --id-prefix files. --detail full --json

Replace <session-id> with the connected session ID. The tool result lists entries and availableRoots. A root is a named, approved directory on the app’s device; path is relative to it. Copy a file’s relativePath into the commands below, and use its rootAlias if it is outside appData.

Read a text file

Read a log or configuration file without changing it:

ansight app call <session-id> files.read_file \
  --arguments '{"root":"appData","path":"<relativePath>","maxBytes":65536,"encoding":"utf8"}' --json

The result includes text. If truncated is true, this is only the beginning of the file; download it to inspect the complete contents.

Download the complete file

Use the same root and relative path to save the file on the computer running the Ansight host:

ansight app call <session-id> files.begin_binary_download \
  --arguments '{"root":"appData","path":"<relativePath>"}' --json

The CLI waits for the transfer to finish. A successful result includes status: "complete" and an artifactPath you can open or copy. The host handles the file transfer; you do not need to decode its data or assemble chunks.

Upload a file from your computer

Uploading requires WithReadWriteToolAccess() and an available files.push_file tool. Replace ./config.json with a real file on the computer running the CLI:

ansight app push-file <session-id> ./config.json imports \
  --sandbox-root appData --file-name config.json --json

This copies the file to imports/config.json under the app’s appData directory and creates the destination folder if needed. An existing file is preserved unless you explicitly add --overwrite. See the CLI upload options to choose a destination name or require an existing directory.

Install

dotnet add package Ansight.Tools.FileSystem

Register the Suite

using Ansight;
using Ansight.Tools.FileSystem;

var options = Options.CreateBuilder()
    .WithFileSystemTools()
    .WithReadOnlyToolAccess()
    .Build();

Registration API

WithFileSystemTools(): registers the suite with the default sandbox roots only.
WithFileSystemTools(fileSystem => ...): configures additional tagged roots.
AddRoot(tag, path): exposes an extra sandboxed directory under a stable root alias.

Specific Concerns

All access is constrained to approved sandbox roots.
The suite exposes file contents, so it is sensitive even when only read tools are enabled.
files.push_file, files.copy_file, and files.move_file use ToolPolicy.Write and require WithReadWriteToolAccess(), WithAllToolAccess(), or a custom write-enabled ToolGuard.
files.delete_file uses ToolPolicy.Critical and requires WithAllToolAccess() or a custom critical-enabled ToolGuard.

Default roots:

Android: appData, cache, temp
iOS and Mac Catalyst: appData, documents, cache, temp
Additional roots can be tagged with AddRoot(tag, path)

Tool Matrix

Use this reference when you need the full arguments and returned fields for a tool.

Name	Id	Policy	Description
`List Directory`	`files.list_directory`	`Read`	Lists files and folders inside the app sandbox.
`Read File`	`files.read_file`	`Read`	Reads a file from the app sandbox using a constrained path.
`Get File Checksum`	`files.get_file_checksum`	`Read`	Computes one or more checksums for a sandboxed file without returning file contents.
`Download File`	`files.download_file`	`Read`	Downloads a sandboxed file in resumable chunks with text or base64 payloads.
`Begin Binary Download`	`files.begin_binary_download`	`Read`	Starts a binary WebSocket download for a sandboxed file.
`Push File`	`files.push_file`	`Write`	Writes caller-provided content into a folder inside an approved sandbox root.
`Copy File`	`files.copy_file`	`Write`	Copies a sandboxed file to another constrained sandbox path.
`Move File`	`files.move_file`	`Write`	Moves or renames a sandboxed file inside approved roots.
`Delete File`	`files.delete_file`	`Critical`	Deletes a sandboxed file from an approved root.

List Directory

Arguments:

root: optional root alias
path: optional relative directory path
includeHidden
recursive
maxDepth
maxEntries

Returns:

resolved root and directory metadata
availableRoots
entries
truncated
capturedAtUtc

Example:

{
  "toolId": "files.list_directory",
  "arguments": {
    "root": "appData",
    "path": "databases",
    "recursive": true,
    "maxDepth": 2,
    "maxEntries": 200
  }
}

Read File

Arguments:

root: optional root alias
path: required file path
maxBytes
encoding: auto, utf8, or base64

Returns:

resolved file metadata
bytesRead
truncated
contentType
encoding
text or base64

Example:

{
  "toolId": "files.read_file",
  "arguments": {
    "root": "appData",
    "path": "logs/latest.log",
    "maxBytes": 65536,
    "encoding": "utf8"
  }
}

Get File Checksum

Arguments:

root: optional root alias
path: required file path
algorithms: optional comma-separated list of md5, sha1, sha256, sha384, sha512, crc32, or all; defaults to sha256

Returns:

resolved file metadata
fileName, fileExtension, mimeType
sizeBytes, lastModifiedUtc, version
checksums

Example:

{
  "toolId": "files.get_file_checksum",
  "arguments": {
    "root": "appData",
    "path": "exports/session.json",
    "algorithms": "sha256,crc32"
  }
}

Copy File

Arguments:

root: optional source root alias
sourcePath: required source file path relative to the source root
destinationRoot: optional destination root alias
destinationPath: required destination file path relative to the destination root
overwrite: replace an existing destination file
createDirectory: create the destination folder when missing

Returns:

resolved source and destination metadata
sizeBytes
operation
overwritten
createdDirectory
capturedAtUtc

Example:

{
  "toolId": "files.copy_file",
  "arguments": {
    "root": "appData",
    "sourcePath": "imports/config.json",
    "destinationRoot": "cache",
    "destinationPath": "debug/config-copy.json",
    "overwrite": true,
    "createDirectory": true
  }
}

Move File

Arguments:

root: optional source root alias
sourcePath: required source file path relative to the source root
destinationRoot: optional destination root alias
destinationPath: required destination file path relative to the destination root
overwrite: replace an existing destination file
createDirectory: create the destination folder when missing

Returns:

resolved source and destination metadata
sizeBytes
operation
overwritten
createdDirectory
capturedAtUtc

Example:

{
  "toolId": "files.move_file",
  "arguments": {
    "root": "appData",
    "sourcePath": "imports/config.json",
    "destinationPath": "imports/config.active.json",
    "overwrite": true,
    "createDirectory": false
  }
}

Delete File

Arguments:

root: optional root alias
path: required file path relative to the root

Returns:

resolved deleted file metadata
deleted
capturedAtUtc

Example:

{
  "toolId": "files.delete_file",
  "arguments": {
    "root": "cache",
    "path": "debug/config-copy.json"
  }
}

Custom client transfer reference

The following details are for clients that implement file transfers outside the Ansight CLI and resident host. For ordinary downloads and uploads, use the commands in Work with app files.

A custom client can use files.download_file to receive chunks in JSON, or files.begin_binary_download when it supports binary WebSocket transfers. The app SDK returns file content and transfer metadata; the receiving client chooses where to save it.

Download File

Arguments:

root: optional root alias
path: required file path
offsetBytes
maxBytes
encoding: auto, utf8, or base64
expectedVersion

Returns:

chunk metadata
fileName, fileExtension, mimeType
sizeBytes, lastModifiedUtc, version
hasMore
nextOffsetBytes
nextRequest
encoded chunk content

Example:

{
  "toolId": "files.download_file",
  "arguments": {
    "root": "appData",
    "path": "exports/session.json",
    "offsetBytes": 0,
    "maxBytes": 262144,
    "encoding": "utf8"
  }
}

Begin Binary Download

Arguments:

root: optional root alias
path: required file path
chunkBytes
downloadId: optional caller correlation id

Returns:

resolved file metadata
downloadId
transferId
fileName, fileExtension, mimeType
sizeBytes, lastModifiedUtc, version
deliveryMode = websocket_binary
wireProtocol = ansight.file-transfer.v1
status
chunkBytes

Example:

{
  "toolId": "files.begin_binary_download",
  "arguments": {
    "root": "appData",
    "path": "exports/archive.zip",
    "chunkBytes": 65536,
    "downloadId": "session-archive"
  }
}

Binary Download Notes

When implementing a client for files.begin_binary_download:

Choose a local destination file.
Call files.begin_binary_download.
Associate the returned transferId with that file.
Write incoming ASFT binary frames until the transfer completes.

The Ansight host already performs these steps and returns artifactPath to CLI callers. The app SDK does not choose a path on the receiving computer.

Push File

files.push_file writes content into a destination folder under an approved sandbox root. Use contentBase64 for arbitrary files or text for UTF-8 text payloads. Provide exactly one content field.

Arguments:

root: optional root alias
directoryPath: required destination folder path relative to the root
fileName: required destination file name, not a path
contentBase64: base64-encoded file content
text: UTF-8 text content
overwrite: replace an existing destination file
createDirectory: create the destination folder when missing

Returns:

resolved destination file metadata
sizeBytes
operation
overwritten
createdDirectory
capturedAtUtc

Example:

{
  "toolId": "files.push_file",
  "arguments": {
    "root": "appData",
    "directoryPath": "imports",
    "fileName": "config.json",
    "contentBase64": "eyJkZWJ1ZyI6dHJ1ZX0=",
    "overwrite": true,
    "createDirectory": true
  }
}

Host upload arguments

The app SDK cannot read files from the host computer. The resident host’s upload wrapper accepts localFilePath, reads that file, and sends its bytes as contentBase64 to files.push_file:

{
  "localFilePath": "/Users/example/Desktop/config.json",
  "root": "appData",
  "directoryPath": "imports",
  "fileName": "config.json",
  "overwrite": true,
  "createDirectory": true
}

If you call the app tool directly, supply text or contentBase64 as documented in Push File; localFilePath is a host-wrapper argument, not an app-tool argument. The app must still have FileSystem tools registered and allow ToolPolicy.Write.