@royaltyport/cli 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @royaltyport/cli
+
+Command-line interface for Royaltyport. Authenticate, browse projects, and execute commands in project sandboxes.
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Installation
+
+```bash
+npm install -g @royaltyport/cli
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/royaltyport/royaltyport-cli.git
+cd royaltyport-cli
+npm install
+npm link
+```
+
+## Authentication
+
+### Interactive login
+
+```bash
+royaltyport login
+```
+
+You'll be prompted for your API token (`rp_...`). The token is validated against the API and stored locally.
+
+### Token flag
+
+```bash
+royaltyport login --token rp_your_token_here
+```
+
+### Environment variables
+
+For CI/CD or AI agent integrations, set these environment variables instead of running `login`:
+
+| Variable             | Description                                              |
+| -------------------- | -------------------------------------------------------- |
+| `ROYALTYPORT_TOKEN`  | API token — overrides the stored token                   |
+| `ROYALTYPORT_API_URL`| Custom API base URL (default: `https://api.royaltyport.com`) |
+
+### Custom API URL
+
+```bash
+royaltyport login --api-url https://your-api-url.com
+```
+
+### Logout
+
+```bash
+royaltyport logout
+```
+
+## Commands
+
+### `royaltyport projects`
+
+List all accessible projects.
+
+```bash
+royaltyport projects
+```
+
+```
+ID                                     Name                Created
+─────────────────────────────────────  ──────────────────  ──────────
+a1b2c3d4-...                           Record Label Ltd    1/15/2025
+e5f6g7h8-...                           Publishing Co       3/22/2025
+```
+
+### `royaltyport project info <project_id>`
+
+Display the AGENTS.md from the project sandbox — a filesystem overview with instructions for navigating project data.
+
+```bash
+royaltyport project info a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+### `royaltyport project exec <project_id> "<command>"`
+
+Execute a single bash command in the project sandbox. Commands run with the sandbox workspace root as the working directory.
+
+```bash
+# List all contract folders
+royaltyport project exec $PROJECT_ID "ls contracts/"
+
+# Read project stats
+royaltyport project exec $PROJECT_ID "cat stats.yaml"
+
+# Search for an entity by name
+royaltyport project exec $PROJECT_ID "grep -rl 'Sony Music' entities/"
+
+# Read a contract's extracted royalties
+royaltyport project exec $PROJECT_ID "cat contracts/contract_123/extracted/royalties.yaml"
+```
+
+stdout and stderr are written to their respective streams, and the process exits with the command's exit code — making it suitable for scripting and AI agent tool use.
+
+## Agent Skill
+
+This repo includes a [skills.sh](https://skills.sh/)-compatible skill that teaches AI agents how to use the CLI to explore and query Royaltyport project data.
+
+Install it into your agent:
+
+```bash
+npx skills add royaltyport/royaltyport-cli
+```
+
+The skill covers authentication, project discovery, filesystem layout, and common data access patterns — everything an agent needs to send the right `project exec` commands.
+
+## Configuration
+
+Credentials and settings are stored at `~/.config/royaltyport/config.json` (managed by [conf](https://github.com/sindresorhus/conf)). Running `royaltyport logout` clears this file.
+
+## License
+
+UNLICENSED

package/bin/royaltyport.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { registerLoginCommand } from '../src/commands/login.js';
+import { registerLogoutCommand } from '../src/commands/logout.js';
+import { registerProjectsCommand } from '../src/commands/projects.js';
+import { registerProjectCommand } from '../src/commands/project.js';
+
+program
+  .name('royaltyport')
+  .description('Royaltyport CLI — authenticate, list projects, and execute commands in a sandboxed project filesystem')
+  .version('0.1.0');
+
+registerLoginCommand(program);
+registerLogoutCommand(program);
+registerProjectsCommand(program);
+registerProjectCommand(program);
+
+program.parse();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@royaltyport/cli",
+  "version": "0.1.0",
+  "description": "Royaltyport CLI — authenticate, list projects, and connect to project file systems",
+  "type": "module",
+  "bin": {
+    "royaltyport": "bin/royaltyport.js"
+  },
+  "scripts": {
+    "start": "node bin/royaltyport.js",
+    "lint": "eslint"
+  },
+  "keywords": [
+    "royaltyport",
+    "cli"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "conf": "^13.1.0",
+    "ora": "^8.2.0"
+  }
+}

package/skills/royaltyport-sandbox/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: royaltyport-sandbox
+description: Access Royaltyport project data via the CLI sandbox. Use when working with music royalty contracts, entities, artists, writers, relations, recordings, compositions, or statements.
+metadata:
+  author: royaltyport
+  version: "0.1.0"
+---
+
+# Skill: Royaltyport Sandbox
+
+Access Royaltyport project data through the CLI. All project data is stored as YAML files in a sandboxed filesystem. You execute bash commands against the sandbox — no SDK or API calls needed.
+
+## Prerequisites
+
+Install the CLI and authenticate:
+
+```bash
+npm install -g @royaltyport/cli
+```
+
+Set your API token as an environment variable (preferred for agents):
+
+```bash
+export ROYALTYPORT_TOKEN=rp_your_token_here
+```
+
+Or authenticate interactively:
+
+```bash
+royaltyport login
+```
+
+## Discovery
+
+### List available projects
+
+```bash
+royaltyport projects
+```
+
+### Get the full filesystem overview for a project
+
+```bash
+royaltyport project info <project_id>
+```
+
+This prints the project's AGENTS.md — a detailed breakdown of every directory, file type, and YAML field available in the sandbox.
+
+## Executing Commands
+
+Run any bash command in the sandbox with `project exec`. Commands run with the workspace root as the working directory. Use relative paths directly.
+
+```bash
+royaltyport project exec <project_id> "<command>"
+```
+
+stdout and stderr stream to their respective outputs. The process exits with the command's exit code.
+
+## Filesystem Layout
+
+```
+stats.yaml                              # Record counts for all resource types
+contracts/contract_{id}/                 # Per-contract data
+  uploaded.yaml                         #   File metadata (id, file_name, file_type)
+  extracted/                            #   AI-extracted contract terms
+    royalties.yaml, entities.yaml, dates.yaml, control_areas.yaml,
+    compensations.yaml, costs.yaml, artists.yaml, writers.yaml,
+    recordings.yaml, compositions.yaml, signatures.yaml, splits.yaml,
+    accounting_period.yaml, languages.yaml, types.yaml,
+    creative_approvals.yaml, targets.yaml, commitments.yaml
+  relationships/                        #   Parent/sibling/child links
+  statements.yaml                       #   Linked statements
+entities/entity_{id}/                   # metadata.yaml, merged.yaml, relations.yaml, artists.yaml, writers.yaml
+artists/artist_{id}/                    # metadata.yaml, merged.yaml, entities.yaml
+writers/writer_{id}/                    # metadata.yaml, merged.yaml, entities.yaml
+relations/relation_{id}/                # metadata.yaml, merged.yaml, entities.yaml
+recordings/recording_{id}/              # metadata.yaml, products.yaml, tracks.yaml
+compositions/composition_{id}/          # metadata.yaml, products.yaml, tracks.yaml
+statements/
+  statement_{id}/                       # metadata.yaml, contracts.yaml
+  recordings/statement_{id}/assets.yaml # Recording assets (isrc, upc, matched)
+  compositions/statement_{id}/assets.yaml # Composition assets (iswc, work_id, matched)
+```
+
+## Common Data Access Patterns
+
+### Project overview
+
+```bash
+royaltyport project exec $PROJECT_ID "cat stats.yaml"
+```
+
+### Find contracts
+
+```bash
+# List all contracts
+royaltyport project exec $PROJECT_ID "ls contracts/"
+
+# Find contract by name
+royaltyport project exec $PROJECT_ID "grep -ril 'CONTRACT_NAME' contracts/contract_*/uploaded.yaml"
+
+# Find contracts involving an entity
+royaltyport project exec $PROJECT_ID "grep -ril 'ENTITY_NAME' contracts/contract_*/extracted/entities.yaml"
+```
+
+### Read contract details
+
+```bash
+# File metadata
+royaltyport project exec $PROJECT_ID "cat contracts/contract_{id}/uploaded.yaml"
+
+# Extracted terms
+royaltyport project exec $PROJECT_ID "cat contracts/contract_{id}/extracted/royalties.yaml"
+royaltyport project exec $PROJECT_ID "cat contracts/contract_{id}/extracted/splits.yaml"
+royaltyport project exec $PROJECT_ID "ls contracts/contract_{id}/extracted/"
+```
+
+### Find artists, writers, entities
+
+```bash
+# Search by name
+royaltyport project exec $PROJECT_ID "grep -rl 'SEARCH_TERM' artists/"
+royaltyport project exec $PROJECT_ID "grep -rl 'SEARCH_TERM' writers/"
+royaltyport project exec $PROJECT_ID "grep -rl 'SEARCH_TERM' entities/"
+
+# List all artist names
+royaltyport project exec $PROJECT_ID "grep -rh '^name:' artists/artist_*/metadata.yaml | sort"
+
+# Read artist details
+royaltyport project exec $PROJECT_ID "cat artists/artist_{id}/metadata.yaml"
+royaltyport project exec $PROJECT_ID "cat artists/artist_{id}/merged.yaml"
+```
+
+### Find recordings and compositions
+
+```bash
+# Search by name or ISRC/ISWC
+royaltyport project exec $PROJECT_ID "grep -rl 'SEARCH_TERM' recordings/"
+royaltyport project exec $PROJECT_ID "grep -rl 'ISWC_CODE' compositions/"
+
+# Read recording details
+royaltyport project exec $PROJECT_ID "cat recordings/recording_{id}/metadata.yaml"
+```
+
+### Browse statements
+
+```bash
+# List statements
+royaltyport project exec $PROJECT_ID "ls statements/ | head -20"
+
+# Read statement metadata
+royaltyport project exec $PROJECT_ID "cat statements/statement_{id}/metadata.yaml"
+
+# Read matched recording assets on a statement
+royaltyport project exec $PROJECT_ID "cat statements/recordings/statement_{id}/assets.yaml"
+```
+
+## Tips
+
+- **Always start with `stats.yaml`** to understand how much data the project has.
+- **Use `grep -rl`** for searching across files, `grep -rh` for extracting values.
+- **Check `merged.yaml`** — artists, writers, and entities may have duplicates merged into a root record.
+- **All data is plain-text YAML** — standard Unix tools (`grep`, `cat`, `find`, `wc`, `sort`, `head`) all work.
+- **Contract extractions** under `extracted/` are AI-extracted terms. One YAML file per category.

package/src/commands/login.js

@@ -0,0 +1,54 @@
+import { createInterface } from 'node:readline/promises';
+import ora from 'ora';
+import { apiGet } from '../lib/api.js';
+import { setToken, setApiUrl, getConfigPath } from '../lib/config.js';
+import { printError, printSuccess, printInfo } from '../lib/output.js';
+import { spinnerColor, dim } from '../lib/theme.js';
+
+export function registerLoginCommand(program) {
+  program
+    .command('login')
+    .description('Authenticate with your Royaltyport API token')
+    .option('-t, --token <token>', 'API token (rp_...)')
+    .option('--api-url <url>', 'Custom API URL (default: https://api.royaltyport.com)')
+    .action(async (options) => {
+      try {
+        let token = options.token;
+
+        if (!token) {
+          const rl = createInterface({ input: process.stdin, output: process.stdout });
+          token = await rl.question('Enter your API token (rp_...): ');
+          rl.close();
+        }
+
+        token = token.trim();
+        if (!token) {
+          printError('Token cannot be empty.');
+          process.exit(1);
+        }
+
+        if (options.apiUrl) {
+          setApiUrl(options.apiUrl);
+        }
+
+        const spinner = ora({ text: 'Validating token...', color: spinnerColor }).start();
+
+        try {
+          const response = await apiGet('/v1/projects', token);
+          const projectCount = Array.isArray(response.data) ? response.data.length : 0;
+          spinner.succeed(`Authenticated successfully (${projectCount} project${projectCount !== 1 ? 's' : ''} accessible)`);
+        } catch (err) {
+          spinner.fail('Token validation failed');
+          printError(err.message);
+          process.exit(1);
+        }
+
+        setToken(token);
+        printSuccess('Token saved.');
+        printInfo(`Config stored at ${dim(getConfigPath())}`);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/logout.js

@@ -0,0 +1,12 @@
+import { clearConfig } from '../lib/config.js';
+import { printSuccess } from '../lib/output.js';
+
+export function registerLogoutCommand(program) {
+  program
+    .command('logout')
+    .description('Clear stored credentials')
+    .action(() => {
+      clearConfig();
+      printSuccess('Logged out. Credentials cleared.');
+    });
+}

package/src/commands/project.js

@@ -0,0 +1,60 @@
+import ora from 'ora';
+import { apiPost, apiGet, requireAuth } from '../lib/api.js';
+import { printError, printInfo } from '../lib/output.js';
+import { warning, spinnerColor } from '../lib/theme.js';
+
+export function registerProjectCommand(program) {
+  const project = program
+    .command('project')
+    .description('Use bash commands to explore a project filesystem');
+
+  project
+    .command('info')
+    .description('Show the AGENTS.md for a project sandbox (filesystem overview and instructions)')
+    .argument('<project_id>', 'Project ID')
+    .action(async (projectId) => {
+      try {
+        requireAuth();
+
+        const spinner = ora({ text: 'Connecting to sandbox...', color: spinnerColor }).start();
+        await apiPost(`/v1/projects/${projectId}/sandbox/connect`, {});
+        spinner.text = 'Reading AGENTS.md...';
+
+        const response = await apiGet(`/v1/projects/${projectId}/sandbox/files?path=${encodeURIComponent('AGENTS.md')}`);
+        spinner.stop();
+
+        if (response.data?.type === 'file' && response.data.content) {
+          console.log(response.data.content);
+        } else {
+          printInfo('No AGENTS.md found in this project sandbox.');
+        }
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+
+  project
+    .command('exec')
+    .description('Execute a bash command in a project sandbox')
+    .argument('<project_id>', 'Project ID')
+    .argument('<command>', 'Bash command to execute')
+    .action(async (projectId, command) => {
+      try {
+        requireAuth();
+
+        await apiPost(`/v1/projects/${projectId}/sandbox/connect`, {});
+
+        const response = await apiPost(`/v1/projects/${projectId}/sandbox/exec`, { command });
+        const { stdout, stderr, exitCode } = response.data;
+
+        if (stdout) process.stdout.write(stdout);
+        if (stderr) process.stderr.write(warning(stderr));
+
+        process.exit(exitCode);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/projects.js

@@ -0,0 +1,36 @@
+import ora from 'ora';
+import { apiGet, requireAuth } from '../lib/api.js';
+import { printTable, printError, printInfo } from '../lib/output.js';
+import { spinnerColor } from '../lib/theme.js';
+
+export function registerProjectsCommand(program) {
+  program
+    .command('projects')
+    .description('List available projects')
+    .action(async () => {
+      try {
+        requireAuth();
+
+        const spinner = ora({ text: 'Fetching projects...', color: spinnerColor }).start();
+        const response = await apiGet('/v1/projects');
+        spinner.stop();
+
+        const projects = response.data;
+        if (!projects || projects.length === 0) {
+          printInfo('No projects found.');
+          return;
+        }
+
+        const rows = projects.map((p) => [
+          p.id,
+          p.name,
+          new Date(p.created_at).toLocaleDateString(),
+        ]);
+
+        printTable(['ID', 'Name', 'Created'], rows);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/lib/api.js

@@ -0,0 +1,79 @@
+import { getToken, getApiUrl } from './config.js';
+
+class ApiError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function buildHeaders(token) {
+  return {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  };
+}
+
+async function parseResponse(res) {
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+export function requireAuth() {
+  const token = getToken();
+  if (!token) {
+    throw new ApiError('Not authenticated. Run `royaltyport login` first.', 401);
+  }
+  return token;
+}
+
+export async function apiGet(path, token) {
+  const baseUrl = getApiUrl();
+  const res = await fetch(`${baseUrl}${path}`, {
+    method: 'GET',
+    headers: buildHeaders(token || requireAuth()),
+  });
+  const body = await parseResponse(res);
+  if (!res.ok) {
+    const msg = body?.error?.message || body?.message || `Request failed with status ${res.status}`;
+    throw new ApiError(msg, res.status, body);
+  }
+  return body;
+}
+
+export async function apiPost(path, data, token) {
+  const baseUrl = getApiUrl();
+  const res = await fetch(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: buildHeaders(token || requireAuth()),
+    body: JSON.stringify(data),
+  });
+  const body = await parseResponse(res);
+  if (!res.ok) {
+    const msg = body?.error?.message || body?.message || `Request failed with status ${res.status}`;
+    throw new ApiError(msg, res.status, body);
+  }
+  return body;
+}
+
+export async function apiDelete(path, token) {
+  const baseUrl = getApiUrl();
+  const res = await fetch(`${baseUrl}${path}`, {
+    method: 'DELETE',
+    headers: buildHeaders(token || requireAuth()),
+  });
+  const body = await parseResponse(res);
+  if (!res.ok) {
+    const msg = body?.error?.message || body?.message || `Request failed with status ${res.status}`;
+    throw new ApiError(msg, res.status, body);
+  }
+  return body;
+}
+
+export { ApiError };

package/src/lib/config.js

@@ -0,0 +1,33 @@
+import Conf from 'conf';
+
+const config = new Conf({
+  projectName: 'royaltyport',
+  schema: {
+    token: { type: 'string', default: '' },
+    apiUrl: { type: 'string', default: 'https://api.royaltyport.com' },
+  },
+});
+
+export function getToken() {
+  return process.env.ROYALTYPORT_TOKEN || config.get('token');
+}
+
+export function setToken(token) {
+  config.set('token', token);
+}
+
+export function getApiUrl() {
+  return process.env.ROYALTYPORT_API_URL || config.get('apiUrl');
+}
+
+export function setApiUrl(url) {
+  config.set('apiUrl', url);
+}
+
+export function clearConfig() {
+  config.clear();
+}
+
+export function getConfigPath() {
+  return config.path;
+}

package/src/lib/output.js

@@ -0,0 +1,31 @@
+import { brand, brandBold, dim, error, accent } from './theme.js';
+
+export function printTable(columns, rows) {
+  const widths = columns.map((col, i) => {
+    const maxData = rows.reduce((max, row) => Math.max(max, String(row[i] ?? '').length), 0);
+    return Math.max(col.length, maxData);
+  });
+
+  const header = columns.map((col, i) => col.padEnd(widths[i])).join('  ');
+  const separator = widths.map(w => '─'.repeat(w)).join('──');
+
+  console.log(brandBold(header));
+  console.log(dim(separator));
+
+  for (const row of rows) {
+    const line = row.map((cell, i) => String(cell ?? '').padEnd(widths[i])).join('  ');
+    console.log(line);
+  }
+}
+
+export function printError(message) {
+  console.error(error(`Error: ${message}`));
+}
+
+export function printSuccess(message) {
+  console.log(brand(message));
+}
+
+export function printInfo(message) {
+  console.log(accent(message));
+}

package/src/lib/theme.js

@@ -0,0 +1,14 @@
+import chalk from 'chalk';
+
+export const brand = chalk.green;
+export const accent = chalk.cyan;
+export const dim = chalk.dim;
+export const bold = chalk.bold;
+export const error = chalk.red;
+export const warning = chalk.yellow;
+
+export const spinnerColor = 'white';
+
+export function brandBold(text) {
+  return chalk.bold(text);
+}