Struct CLI

Command-line tool for working on Struct agent sessions locally and continuing development with Claude Code.

Installation

# Install globally
npm install -g @struct-ai/cli

# Or use with npx (no installation required)
npx @struct-ai/cli <command>

Usage

Login

Authenticate with Struct using OAuth:

struct login

Required options (choose one):

• --pr-url – GitHub pull request URL created by the agent
• --issue-url – Linear issue URL associated with the session
• --thread-url – Slack thread URL from a conversation with the agent
• --task-url – Asana task URL associated with the session
• --session-url – Session share URL from the Struct dashboard

This will:

1. Open your browser to the Struct authorization page
2. Ask you to approve access for the CLI
3. Store your access token locally in ~/.struct/config.json

The token is valid for 30 days.

Local

Prepare an agent session locally from a GitHub PR:

# By PR URL
struct local --pr-url https://github.com/owner/repo/pull/123

# By Linear issue URL
struct local --issue-url https://linear.app/acme/issue/RND-123

# By Slack thread URL
struct local --thread-url https://workspace.slack.com/archives/C12345/p1234567890123456

# By Asana task URL
struct local --task-url https://app.asana.com/0/PROJECT_ID/TASK_ID

# By session share URL
struct local --session-url https://app.struct.ai/issues/{session_id}

This will:

1. Validate that you are inside the matching Git repository (based on the PR owner/name)
2. Restore the Claude session file as ~/.claude/projects/{sanitized_repo_path}/{claude_session_id}.jsonl
3. Fetch and check out the PR branch locally
4. Launch Claude (claude -r <session_id>) in the repo root

Prerequisites

• You must be logged in (struct login)
• The PR must have been created by a Struct agent session
• You must have access to the tenant that owns the session
• Run the command from within the local clone of the target repository

Example output:

🔧 Struct Local Session Setup

PR URL: https://github.com/owner/repo/pull/123

🔍 Fetching session information...

✅ Found agent session!

Session Information:
  Session ID: abc-123-def-456
  Agent Type: claude_code
  Status: completed
  Repository: owner/repo
  Branch: feature/new-feature

✅ Using repository at /Users/you/src/owner/repo

📁 Restored Claude session to: /Users/you/.claude/projects/Users-you-src-owner-repo/xyz-789.jsonl

✅ Checked out branch feature/new-feature

🚀 Launching Claude session xyz-789...

... (Claude CLI output) ...

✅ Claude session closed. Happy debugging!

Logout

Remove stored credentials:

struct logout

This removes the config file at ~/.struct/config.json.

Configuration

The CLI stores configuration in ~/.struct/config.json, which contains:

• OAuth access token
• Token expiration time
• OAuth scope

The file has restricted permissions (0600) for security.

Environment Variables

You can override default settings using environment variables:

• STRUCT_API_URL - API base URL (default: https://api.struct.ai)

Development

Setup

cd packages/edgedive-cli
pnpm install
pnpm build

Link for local testing

npm link

Now you can run struct commands from anywhere.

Build

pnpm build

Compiles TypeScript to JavaScript in the dist/ directory.

Building and Publishing

Build Process

The CLI is built using TypeScript and compiled to CommonJS modules in the dist/ directory:

1. TypeScript Compilation: pnpm build runs tsc which:

   • Compiles all TypeScript files from src/ to dist/
   • Generates type declarations (.d.ts files)
   • Creates source maps for debugging
   • Outputs ES2022-compatible JavaScript modules

2. What Gets Published:

   • dist/ directory (compiled JavaScript + type declarations)
   • package.json
   • README.md
   • The bin field in package.json points to dist/index.js for the struct command

Publishing to npm

The package is published to npm under the @struct-ai/cli scope.

Prerequisites

1. npm account with access to the @struct-ai organization
2. Logged in to npm: npm login
3. Clean build: pnpm clean && pnpm build

Publishing Steps

# From the packages/edgedive-cli directory

# 1. Ensure you're on main and up to date
git checkout main
git pull origin main

# 2. Clean and build
pnpm clean
pnpm build

# 3. Test the built CLI
node dist/index.js --help

# 4. Update version (choose one)
npm version patch  # 0.1.6 -> 0.1.7
npm version minor  # 0.1.6 -> 0.2.0
npm version major  # 0.1.6 -> 1.0.0

# 5. Publish to npm
npm publish --access public

# 6. Push the version tag
git push origin main --tags

Current Published Version

Latest: 0.3.1

Continuous Integration

The CI pipeline (.github/workflows/ci.yml) automatically:

• Detects changes to packages/edgedive-cli/**
• Runs pnpm build --filter @struct-ai/cli
• Tests the built CLI with node dist/index.js --help

Note: Publishing to npm is currently a manual process. Consider setting up automated releases via GitHub Actions when appropriate.

OAuth Flow

The CLI uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication:

1. CLI generates a code verifier and code challenge
2. Opens browser to authorization URL with code challenge
3. User approves access in the Struct web UI
4. Authorization server redirects to local callback server (http://localhost:8765)
5. CLI exchanges authorization code for access token using code verifier
6. Token is stored locally for future requests

The token is scoped to your tenant and allows read/write access as configured.

Troubleshooting

"You are not logged in"

Run struct login to authenticate.

"Your session may have expired"

Tokens expire after 30 days. Run struct login to refresh.

"No agent session found for PR"

The PR may not have been created by a Struct agent, or you may not have access to the tenant.

"Failed to download file"

The presigned URLs expire after 1 hour. If this happens, run the local command again to generate fresh URLs.

Browser doesn't open during login

Copy the URL from the terminal and paste it into your browser manually.

Security

• OAuth tokens are stored with restricted file permissions (0600)
• PKCE prevents authorization code interception attacks
• Tokens are scoped to specific tenants
• Presigned S3 URLs expire after 1 hour
• Local callback server only accepts connections from localhost

License

UNLICENSED - Internal Struct tool