Turbostash CLI

Command-line interface for Turbostash remote cache service, compatible with Turborepo Remote Cache API (V8).

Installation

Global Installation

npm install -g turbostash

After installation, you can use the turbostash command from anywhere:

turbostash --help

Local Installation

npm install turbostash

Then use via npx:

npx turbostash --help

Commands

turbostash init

Initialize Turbostash in the current project.

turbostash init

turbostash auth

Authenticate with Turbostash (login).

turbostash auth

turbostash logout

Log out from Turbostash.

turbostash logout

turbostash whoami

Display current user and team information.

turbostash whoami

turbostash tokens

Manage API tokens.

List tokens

turbostash tokens list

Create a new token

turbostash tokens create

Revoke a token

turbostash tokens revoke <token-id>

turbostash config

Show current configuration.

turbostash config

turbostash link

Link current directory to a team.

turbostash link

turbostash env

Configure environment variables.

turbostash env

Local Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Setup

1. Clone the repository:

git clone <repository-url>
cd turbostash

1. Install dependencies:

pnpm install

1. Build the CLI:

cd apps/cli
pnpm build

Testing Locally

Using npm link

1. From the apps/cli directory, create a global link:

npm link

1. Now you can use turbostash from anywhere:

turbostash --help

1. To unlink:

npm unlink -g turbostash

Using pnpm link

1. From the apps/cli directory:

pnpm link --global

1. Use turbostash from anywhere:

turbostash --help

1. To unlink:

pnpm unlink --global turbostash

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

Development Workflow

1. Make changes to source files in src/
2. Build the project:

pnpm build

1. Test your changes:

# Using npm link (if linked)
turbostash init

# Or directly with node
node dist/index.js init

Publishing

Prerequisites

• npm account with access to publish turbostash package
• Authenticated with npm: npm login

Build Process

The package uses TypeScript and must be compiled before publishing:

pnpm build

This compiles TypeScript files from src/ to dist/.

Version Bumping

Update the version in package.json following Semantic Versioning:

• Patch (0.1.0 → 0.1.1): Bug fixes
• Minor (0.1.0 → 0.1.0): New features, backward compatible
• Major (0.1.0 → 1.0.0): Breaking changes

You can use npm version commands:

npm version patch  # 0.1.0 → 0.1.1
npm version minor  # 0.1.0 → 0.2.0
npm version major  # 0.1.0 → 1.0.0

This automatically updates package.json and creates a git tag.

Publishing Steps

1. Ensure you're in the correct directory:

cd apps/cli

1. Build the package:

pnpm build

1. Verify the build output:

ls -la dist/

You should see compiled JavaScript files.

1. Test the binary locally:

node dist/index.js --help

1. Check what will be published:

npm pack --dry-run

This shows what files will be included in the package.

1. Publish to npm:

npm publish

For scoped packages or first-time publishing, you might need:

npm publish --access public

Publishing Checklist

• [ ] All tests pass (pnpm test)
• [ ] TypeScript compiles without errors (pnpm build)
• [ ] Version updated in package.json
• [ ] Build output verified (ls dist/)
• [ ] Binary tested locally (node dist/index.js --help)
• [ ] npm pack --dry-run shows expected files
• [ ] Git changes committed (if using npm version)
• [ ] Ready to publish

Post-Publishing

After publishing:

1. Verify installation:

npm install -g turbostash
turbostash --version

1. Test the published package:

turbostash init

1. Update documentation if needed

Project Structure

apps/cli/
├── src/
│   ├── index.ts          # Main CLI entry point
│   ├── commands/         # Command implementations
│   │   ├── init.ts
│   │   ├── auth.ts
│   │   ├── logout.ts
│   │   ├── whoami.ts
│   │   ├── tokens.ts
│   │   ├── config.ts
│   │   ├── link.ts
│   │   └── env.ts
│   └── utils/
│       └── output.ts     # Shared utilities
├── tests/                # Test files
│   ├── commands/
│   └── helpers.ts
├── dist/                 # Compiled output (generated)
├── package.json
├── tsconfig.json
└── README.md

Requirements

• Node.js 18.0.0 or higher

License

MIT