triform-cli 0.1.0

CLI tool to sync and execute Triform projects

Triform CLI

A command-line tool to sync and execute Triform projects locally. Perfect for integrating with Cursor or any IDE.

Installation

From PyPI (Recommended)

pip install triform-cli

Or using pipx (isolated environment):

pipx install triform-cli

From GitHub

pip install git+https://github.com/triform/triform-cli.git

Development Install

git clone https://github.com/triform/triform-cli.git
cd triform-cli
pip install -e ".[dev]"

Quick Start

1. Authenticate

# Login with your session token from the browser
triform auth login --token YOUR_SESSION_TOKEN

To get your session token:

1. Login to https://app.triform.ai
2. Open browser DevTools (F12)
3. Go to Application > Cookies
4. Copy the value of __Secure-better-auth.session_token

2. Pull a Project

# List your projects
triform projects list

# Pull a project to local files
triform projects pull <project-id>

This creates a local directory structure:

Triform/                        # Root directory
└── OrgName/                    # Organization
    └── my-project/             # Project
        ├── .triform/
        │   ├── config.json     # Project & org ID mapping
        │   └── state.json      # Sync state
        ├── project.json        # Project metadata & environment
        ├── requirements.json   # Project requirements
        ├── actions/
        │   └── my-action/
        │       ├── source.py       # Action code
        │       ├── meta.json       # Component metadata
        │       ├── requirements.txt
        │       ├── requirements.json  # Component requirements
        │       └── readme.md
        ├── flows/
        │   └── my-flow/
        │       ├── flow.json       # Flow definition
        │       ├── meta.json
        │       ├── requirements.json
        │       └── readme.md
        └── agents/
            └── my-agent/
                ├── agent.json      # Agent configuration
                ├── meta.json
                ├── requirements.json
                └── readme.md

Options:

• --flat - Skip the Triform/Org structure
• --dir <path> - Specify a custom directory

3. Edit Locally

Edit your action code in actions/my-action/source.py or any other files.

4. Push Changes

# Push changes back to Triform
triform projects push

# Or watch for changes and auto-sync
triform projects watch

5. Execute Components

# Execute by component ID
triform execute <component-id> --payload '{"input": "value"}'

# Execute from local project by node key
triform execute my-action --payload '{"input": "value"}'

# Execute with real-time tracing
triform execute my-action --trace

# Execute by project path
triform execute <project-id>/my-action --payload '{}'

Commands

Authentication

triform auth login              # Login with session token
triform auth logout             # Clear authentication
triform auth status             # Check auth status
triform auth whoami             # Show user & organization info

Projects

triform projects list           # List all projects
triform projects pull <id>      # Pull project to local
triform projects push           # Push local changes
triform projects watch          # Watch and auto-sync
triform projects deploy         # Deploy project
triform projects status         # Show sync status

Components

triform component get <id>      # Get component details
triform component build <id>    # Build action dependencies

Execution

triform execute <target>        # Execute a component
triform executions              # List recent executions

Utilities

triform diff                    # Show local vs remote changes

Local Development Workflow

1. Pull your project: triform projects pull <id>
2. Open in Cursor/VS Code
3. Edit action code locally
4. Watch for auto-sync: triform projects watch
5. Execute to test: triform execute my-action --trace
6. Deploy when ready: triform projects deploy

Environment Variables

You can also configure authentication via environment variables:

export TRIFORM_AUTH_TOKEN="your-session-token"
export TRIFORM_API_URL="https://app.triform.ai/api"

File Structure Details

Actions

• source.py - Main Python code
• requirements.txt - pip dependencies
• meta.json - Name, intention, runtime, I/O schemas
• readme.md - Documentation

Flows

• flow.json - Nodes, connections, I/O
• meta.json - Name, intention
• readme.md - Documentation
• components/ - Resolved nested components (read-only)

Agents

• agent.json - Model, prompts, settings, tools
• meta.json - Name, intention
• readme.md - Documentation
• components/ - Resolved nested components (read-only)

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT