CLI

The t-req CLI by default starts the TUI when run without any arguments.

treq

But it also accepts commands as documented on this page. This allows you to interact with t-req programmatically.

treq run "Explain how closures work in JavaScript"

---

tui

Start the t-req terminal user interface.

treq [project]

Flags

Flag	Short	Description
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--prompt		Prompt to use
--model	-m	Model to use in the form of provider/model
--agent		Agent to use
--port		Port to listen on
--hostname		Hostname to listen on

---

Commands

The t-req CLI also has the following commands.

---

agent

Manage agents for t-req.

treq agent [command]

---

attach

Attach a terminal to an already running t-req backend server started via serve or web commands.

treq attach [url]

This allows using the TUI with a remote t-req backend. For example:

# Start the backend server for web/mobile access
treq web --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
treq attach http://10.20.30.40:4096

Flags

Flag	Short	Description
--dir		Working directory to start TUI in
--session	-s	Session ID to continue

---

create

Create a new agent with custom configuration.

treq agent create

This command will guide you through creating a new agent with a custom system prompt and tool configuration.

---

list

List all available agents.

treq agent list

---

auth

Command to manage credentials and login for providers.

treq auth [command]

---

login

t-req is powered by the provider list at Models.dev, so you can use treq auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/treq/auth.json.

treq auth login

When t-req starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.

---

list

Lists all the authenticated providers as stored in the credentials file.

treq auth list

Or the short version.

treq auth ls

---

logout

Logs you out of a provider by clearing it from the credentials file.

treq auth logout

---

github

Manage the GitHub agent for repository automation.

treq github [command]

---

install

Install the GitHub agent in your repository.

treq github install

This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.

---

run

Run the GitHub agent. This is typically used in GitHub Actions.

treq github run

Flags

Flag	Description
--event	GitHub mock event to run the agent for
--token	GitHub personal access token

---

mcp

Manage Model Context Protocol servers.

treq mcp [command]

---

add

Add an MCP server to your configuration.

treq mcp add

This command will guide you through adding either a local or remote MCP server.

---

list

List all configured MCP servers and their connection status.

treq mcp list

Or use the short version.

treq mcp ls

---

auth

Authenticate with an OAuth-enabled MCP server.

treq mcp auth [name]

If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.

You can also list OAuth-capable servers and their authentication status.

treq mcp auth list

Or use the short version.

treq mcp auth ls

---

logout

Remove OAuth credentials for an MCP server.

treq mcp logout [name]

---

debug

Debug OAuth connection issues for an MCP server.

treq mcp debug <name>

---

models

List all available models from configured providers.

treq models [provider]

This command displays all models available across your configured providers in the format provider/model.

This is useful for figuring out the exact model name to use in your config.

You can optionally pass a provider ID to filter models by that provider.

treq models anthropic

Flags

Flag	Description
--refresh	Refresh the models cache from models.dev
--verbose	Use more verbose model output (includes metadata like costs)

Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in t-req.

treq models --refresh

---

run

Run treq in non-interactive mode by passing a prompt directly.

treq run [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

treq run Explain the use of context in Go

You can also attach to a running treq serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
treq serve

# In another terminal, run commands that attach to it
treq run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
--command		The command to run, use message for args
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--share		Share the session
--model	-m	Model to use in the form of provider/model
--agent		Agent to use
--file	-f	File(s) to attach to message
--format		Format: default (formatted) or json (raw JSON events)
--title		Title for the session (uses truncated prompt if no value provided)
--attach		Attach to a running treq server (e.g., http://localhost:4096)
--port		Port for the local server (defaults to random port)

---

http

HTTP client commands for executing API requests.

treq http [command]

---

send

Send an ad-hoc HTTP request.

treq http send <method> <url>

Flags

Flag	Short	Description
--header	-H	Headers in ‘Key: Value’ format (can be repeated)
--data	-d	Request body (JSON)
--env	-e	Environment to use for variable interpolation
--timeout	-t	Timeout in seconds
--auth	-a	Auth: bearer <token> | basic <user> <pass> | apiKey <header> <value>
--no-history		Don’t record in history
--verbose	-v	Show full response details

Example

treq http send GET https://api.example.com/users
treq http send POST https://api.example.com/users -d '{"name": "John"}' -H "Content-Type: application/json"

---

run

Execute a saved request from a collection with environment variables and secrets resolved.

treq http run <collection>/<request>

Flags

Flag	Short	Description
--env	-e	Environment to use for variable interpolation
--var		Override variable KEY=value (can be repeated)
--verbose	-v	Show full request/response details
--run-tests		Run tests after request
--no-hooks		Skip pre/post hooks

Variable Overrides

Use --var to override environment variables at runtime without modifying files:

# Override a single variable
treq http run api/get-user -e dev --var USER_ID=123

# Override multiple variables
treq http run api/create-user -e dev \
    --var NAME="John Doe" \
    --var EMAIL="john@example.com"

# Override takes precedence over environment file values
treq http run api/search -e dev --var LIMIT=100

Variables in requests use {{VARIABLE_NAME}} syntax:

• URL path: {{BASE_URL}}/users/{{USER_ID}}
• Headers: Authorization: Bearer {{API_TOKEN}}
• Query params: ?limit={{LIMIT}}
• Request body: { "name": "{{NAME}}" }

---

import

Import an OpenAPI spec into the workspace.

treq http import <source>

Flags

Flag	Short	Description
--name	-n	Name for the imported spec

---

list

List imported API specs.

treq http list

Or use the short version:

treq http ls

---

test

Run tests for requests in a collection. Only requests with a .test.js file are included.

treq test [request] [options]

Flags

Flag	Short	Description
--collection	-c	Collection name to run tests for
--env	-e	Environment to use for variable interpolation
--reporter	-r	Output format: console, json, junit (default: console)
--output	-o	Output file path for json/junit reporters
--fail-fast		Stop on first test failure
--match	-m	Glob pattern to filter request names
--timeout	-t	Request timeout in milliseconds (default: 30000)
--var		Override variable KEY=value (can be repeated)

Examples

# Run all tests in a collection
treq test -c my-api -e staging

# Run a specific request's tests
treq test get-user -c my-api -e staging

# Run tests matching a pattern
treq test -c my-api -e staging --match "get-*"

# Stop on first failure
treq test -c my-api -e staging --fail-fast

# Output JUnit XML for CI
treq test -c my-api -e staging -r junit -o results.xml

# Output JSON
treq test -c my-api -e staging -r json -o results.json

# Run with variable overrides
treq test -c my-api -e staging --var API_VERSION=v2

# Set custom timeout
treq test -c my-api -e staging --timeout 60000

Test Files

Test files use Bun’s test runner and export a default function that receives the request context:

get-user.test.js

import { test, expect } from 'bun:test'

export default (ctx) => {
  test('returns 200', () => {
    expect(ctx.response.status).toBe(200)
  })

  test('returns JSON', () => {
    expect(ctx.response.headers['content-type']).toContain('application/json')
  })

  test('has required fields', () => {
    const body = ctx.response.json()
    expect(body.id).toBeDefined()
    expect(body.name).toBeTypeOf('string')
  })

  test('responds quickly', () => {
    expect(ctx.timing.duration).toBeLessThan(500)
  })
}

Context Object

The test context provides access to:

Property	Description
ctx.request	Request that was sent (method, url, headers, body)
ctx.response	Response received (status, headers, body, json())
ctx.timing	Timing info (startTime, endTime, duration)
ctx.env	Environment variables (including —var overrides)
ctx.store	Session store for sharing data between requests
ctx.secrets	Resolved secrets (read-only)
ctx.log	Logger (info, warn, error, debug)

Exit Codes

Code	Meaning
0	All tests passed
1	One or more tests failed

CI/CD Integration

# GitHub Actions
- name: Run API tests
  run: treq test -c my-api -e staging -r junit -o results.xml

- name: Upload results
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: test-results
    path: results.xml

---

collection

Manage collections within your workspace.

treq collection [command]

Alias: treq col

---

create

Create a new collection.

treq collection create <name>

Example

treq collection create my-api
treq col create payments

---

delete

Delete a collection.

treq collection delete <name>

Flags

Flag	Short	Description
--force	-f	Skip confirmation prompt

Example

treq collection delete old-api
treq col delete old-api --force

---

list

List all collections in the workspace.

treq collection list

Or use the short version:

treq col ls

---

run

Run all requests in a collection sequentially with shared session state.

treq collection run <collection>

Flags

Flag	Short	Description
--env	-e	Environment to use for variable interpolation
--order		Comma-separated request execution order
--fail-fast		Stop on first request failure
--verbose	-v	Show detailed output
--var		Override variable KEY=value (can be repeated)
--run-tests		Run tests after each request

Example

# Run all requests in order
treq collection run auth-service --env local

# Specify execution order
treq collection run auth-service --order login,me --env local

# Stop on first failure
treq collection run auth-service --fail-fast

This is useful for auth flows where the login request extracts a token that subsequent requests need. The session store (ctx.store) is shared across all requests, allowing hooks to pass data between them.

---

request

Manage requests within collections.

treq request [command]

Alias: treq req

---

create

Create a new request in a collection.

treq request create <collection>

Flags

Flag	Short	Description
--name	-n	Request name (required)
--method	-m	HTTP method (default: GET)
--url	-u	Full URL or path
--from-curl		Parse request from curl command
--body	-b	Request body (JSON string)
--header	-H	Headers (repeatable, format: ‘Key: Value’)
--base-url		Base URL for the request
--auth	-a	Auth: bearer <token> | basic <user> <pass> | apiKey <header> <value>

Example

# Create a simple GET request
treq request create my-api --name get-users --url /users

# Create a POST request with body and headers
treq request create my-api \
  --name create-user \
  --method POST \
  --url /users \
  --body '{"name": "John"}' \
  --header "Content-Type: application/json"

# Create from a curl command
treq req create my-api --name get-user --from-curl "curl https://api.example.com/users/1"

# Create with authentication
treq req create my-api --name protected --url /protected --auth "bearer my-token"

---

delete

Delete a request from a collection.

treq request delete <collection> <request>

Flags

Flag	Short	Description
--force	-f	Skip confirmation prompt

Example

treq request delete my-api old-request
treq req delete my-api old-request --force

---

list

List all requests in a collection.

treq request list <collection>

Or use the short version:

treq req ls my-api

---

workspace

Manage the treq workspace in the current directory.

treq workspace [command]

Alias: treq ws

---

init

Initialize a treq workspace in the current or specified directory.

treq workspace init

Flags

Flag	Short	Description
--directory	-d	Directory to initialize (defaults to current)
--name	-n	Workspace name (skip prompt)

---

env

List and manage environments.

treq workspace env [envName]

Flags

Flag	Short	Description
--create	-c	Create a new environment
--set	-s	Set as active environment
--export	-e	Export variables: shell or dotenv
--list	-l	List all environments (default)
--active	-a	Show active environment only

Examples

# List all environments
treq ws env

# Show environment details
treq ws env production

# Create a new environment
treq ws env staging --create

# Set active environment
treq ws env production --set

# Export as shell variables
treq ws env production --export shell

---

env var

Manage environment variables from the command line.

---

var add

Add a new variable to an environment.

treq workspace env <environment> var add <key> [options]

Flag	Short	Description
--value	-v	Variable value (prompted if omitted)
--type	-t	Variable type: text or secret (default: text)
--source	-s	Value source for secrets: env:<VAR_NAME>
--description	-d	Optional description

Examples:

# Add a text variable
treq ws env production var add API_URL --value "https://api.example.com"

# Add a secret (will prompt for value)
treq ws env production var add API_KEY --type secret

# Add a secret with explicit value
treq ws env production var add API_KEY --type secret --value "sk-123..."

# Add a secret that references a system environment variable
treq ws env production var add DB_PASSWORD --type secret --source env:DATABASE_PASSWORD

# Add with description
treq ws env production var add TIMEOUT --value "30" --description "Request timeout in seconds"

---

var set

Update an existing variable’s value.

treq workspace env <environment> var set <key> [value]

If value is omitted, you’ll be prompted to enter it (with masked input for secrets).

Examples:

# Update text variable
treq ws env production var set API_URL "https://api-v2.example.com"

# Update secret value (prompted)
treq ws env production var set API_KEY

---

var delete

Delete a variable from an environment.

treq workspace env <environment> var delete <key> [--force]

Flag	Short	Description
--force	-f	Skip confirmation prompt

---

var toggle

Enable or disable a variable without deleting it.

treq workspace env <environment> var toggle <key>

Example:

treq ws env production var toggle DEBUG  # Toggles enabled state

---

history

View request history.

treq workspace history

Flags

Flag	Short	Description
--limit	-n	Number of entries (default: 20)
--method	-m	Filter by HTTP method
--starred		Show only starred entries
--search	-s	Search in URL

---

serve

Start a headless t-req server for API access. Check out the server docs for the full HTTP interface.

treq serve

This starts an HTTP server that provides API access to treq functionality without the TUI interface.

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Enable mDNS discovery
--cors	Additional browser origin(s) to allow CORS

---

session

Manage t-req sessions.

treq session [command]

---

list

List all t-req sessions.

treq session list

Flags

Flag	Short	Description
--max-count	-n	Limit to N most recent sessions
--format		Output format: table or json (table)

---

stats

Show token usage and cost statistics for your t-req sessions.

treq stats

Flags

Flag	Description
--days	Show stats for the last N days (all time)
--tools	Number of tools to show (all)
--models	Show model usage breakdown (hidden by default). Pass a number to show top N
--project	Filter by project (all projects, empty string: current project)

---

export

Export session data as JSON.

treq export [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

---

import

Import session data from a JSON file or t-req share URL.

treq import <file>

You can import from a local file or an t-req share URL.

treq import session.json
treq import https://opncd.ai/s/abc123

---

web

Start a headless t-req server with a web interface.

treq web

This starts an HTTP server and opens a web browser to access t-req through a web interface.

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Enable mDNS discovery
--cors	Additional browser origin(s) to allow CORS

---

acp

Start an ACP (Agent Client Protocol) server.

treq acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

Flag	Description
--cwd	Working directory
--port	Port to listen on
--hostname	Hostname to listen on

---

uninstall

Uninstall t-req and remove all related files.

treq uninstall

Flags

Flag	Short	Description
--keep-config	-c	Keep configuration files
--keep-data	-d	Keep session data and snapshots
--dry-run		Show what would be removed without removing
--force	-f	Skip confirmation prompts

---

upgrade

Updates treq to the latest version or a specific version.

treq upgrade [target]

To upgrade to the latest version.

treq upgrade

To upgrade to a specific version.

treq upgrade v0.1.48

Flags

Flag	Short	Description
--method	-m	The installation method that was used; curl, npm, pnpm, bun, brew

---

Global Flags

The treq CLI takes the following global flags.

Flag	Short	Description
--help	-h	Display help
--version	-v	Print version number
--print-logs		Print logs to stderr
--log-level		Log level (DEBUG, INFO, WARN, ERROR)

---

Environment variables

t-req can be configured using environment variables.

Variable	Type	Description
TREQ_AUTO_SHARE	boolean	Automatically share sessions
TREQ_GIT_BASH_PATH	string	Path to Git Bash executable on Windows
TREQ_CONFIG	string	Path to config file
TREQ_CONFIG_DIR	string	Path to config directory
TREQ_CONFIG_CONTENT	string	Inline json config content
TREQ_DISABLE_AUTOUPDATE	boolean	Disable automatic update checks
TREQ_DISABLE_PRUNE	boolean	Disable pruning of old data
TREQ_DISABLE_TERMINAL_TITLE	boolean	Disable automatic terminal title updates
TREQ_PERMISSION	string	Inlined json permissions config
TREQ_DISABLE_DEFAULT_PLUGINS	boolean	Disable default plugins
TREQ_DISABLE_LSP_DOWNLOAD	boolean	Disable automatic LSP server downloads
TREQ_ENABLE_EXPERIMENTAL_MODELS	boolean	Enable experimental models
TREQ_DISABLE_AUTOCOMPACT	boolean	Disable automatic context compaction
TREQ_CLIENT	string	Client identifier (defaults to cli)
TREQ_ENABLE_EXA	boolean	Enable Exa web search tools

---

Experimental

These environment variables enable experimental features that may change or be removed.

Variable	Type	Description
TREQ_EXPERIMENTAL	boolean	Enable all experimental features
TREQ_EXPERIMENTAL_ICON_DISCOVERY	boolean	Enable icon discovery
TREQ_EXPERIMENTAL_DISABLE_COPY_ON_SELECT	boolean	Disable copy on select in TUI
TREQ_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH	number	Max output length for bash commands
TREQ_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS	number	Default timeout for bash commands in ms
TREQ_EXPERIMENTAL_OUTPUT_TOKEN_MAX	number	Max output tokens for LLM responses
TREQ_EXPERIMENTAL_FILEWATCHER	boolean	Enable file watcher for entire dir
TREQ_EXPERIMENTAL_OXFMT	boolean	Enable oxfmt formatter
TREQ_EXPERIMENTAL_LSP_TOOL	boolean	Enable experimental LSP tool