Skip to main content
This page covers the app-side integration path:
  • create a filesystem
  • create a task
  • send events
  • inspect messages and files

​
Client Setup

import { TerminalUseClient } from '@terminaluse/sdk';

const client = new TerminalUseClient({
  environment: process.env.TERMINALUSE_BASE_URL ?? 'https://api.terminaluse.com',
  bearerAuth: { token: process.env.TERMINALUSE_API_KEY! },
});

​
Create A Filesystem

Filesystems belong to projects. Projects are the permission boundary; filesystems are the storage. 
const project = await client.projects.create({
  namespace_id: 'ns_123',
  name: 'my-project'
});

const filesystem = await client.filesystems.create({
  project_id: project.id,
  name: 'customer-123'
});

​
Put Files Into It

There are three different file flows:
Use caseSurface
Upload or download the entire filesystem archivetu fs push / tu fs pull or getUploadUrl / getDownloadUrl
Upload or download one fileuploadFile / download_file / downloadFile
Sync /workspace inside the running agentPython ADK sync_down / sync_up
See Workspaces and Filesystems for the full breakdown.

​
Create A Task

Attach either an existing filesystem or a project: 
const task = await client.tasks.create({
  agent_name: 'my-namespace/my-agent',
  filesystem_id: filesystem.id,
  params: {
    goal: 'summarize this repo'
  }
});
If you pass project_id instead of filesystem_id, TerminalUse creates a filesystem for the task automatically.

​
Send Events

await client.tasks.sendEvent({
  task_id: task.id,
  content: {
    type: 'text',
    text: 'please analyze the files'
  }
});

​
Inspect Files

​
File Metadata And Content

const files = await client.filesystems.listFiles({
  filesystem_id: filesystem.id,
  recursive: true
});

const file = await client.filesystems.getFile({
  filesystem_id: filesystem.id,
  file_path: 'output/report.md',
  include_content: true
});

​
Single-File Download

const response = await client.filesystems.downloadFile({
  filesystem_id: filesystem.id,
  path: 'output/report.md'
});
For whole-filesystem transfers, use tu fs push, tu fs pull, getUploadUrl, or getDownloadUrl instead.