# How to Authenticate and Submit Reviews to Bitbucket Cloud Pull Requests with tuicr

> Learn to authenticate and submit reviews to Bitbucket Cloud PRs with tuicr. This guide explains how tuicr uses the bkt CLI for seamless API operations and PR review submission.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-07

---

**tuicr delegates all Bitbucket Cloud authentication and API operations to the external `bkt` CLI, requiring users to configure API tokens through `bkt` before submitting PR reviews via the TUI interface.**

tuicr is a terminal-based code review tool that integrates with multiple forges including Bitbucket Cloud. To authenticate and submit reviews to Bitbucket Cloud PRs, tuicr relies entirely on the external `bkt` CLI tool rather than implementing its own OAuth flow or token storage mechanism.

## Prerequisites and Authentication Setup

Before opening any pull requests, you must configure the `bkt` CLI with valid Bitbucket Cloud credentials. tuicr does not store tokens internally; instead, it invokes `bkt` for every authenticated operation.

Install the Bitbucket CLI:

```bash
brew install avivsinai/tap/bitbucket-cli

```

Authenticate with your API token:

```bash
bkt auth login https://bitbucket.org --kind cloud --web-token

```

This command opens Atlassian's token creation page in your browser. Create an API token with pull-request read and write scopes, paste it into the prompt, and `bkt` will store it in your OS keychain or credential store. Verify the configuration with:

```bash
bkt auth status

```

## Opening a Pull Request in tuicr

Once authenticated, tuicr detects Bitbucket Cloud repositories by scanning Git remotes. In [`src/forge/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/mod.rs) (lines 23-30), the forge detection logic creates a `BitbucketBktBackend` when it encounters remotes hosted on `bitbucket.org`, `altssh.bitbucket.org`, or `api.bitbucket.org`.

Open a specific PR using:

```bash
tuicr pr 830

```

The `BitbucketBktBackend::get_pull_request_diff` method in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs) (lines 20-26) fetches the diff by shelling out to `bkt pr diff`.

## Submitting Reviews via the TUI

Inside the tuicr interface, press `:` to enter command mode, type `submit`, and press Enter. The TUI presents a picker offering **Comment** or **Approve** events for Bitbucket Cloud.

### Posting Comments and Approvals

When you confirm a submission, tuicr builds a `CreateReviewRequest` and delegates to `BitbucketBktBackend::create_review` in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs) (lines 31-39). This method executes three distinct operations:

- Posts an optional review-level comment via `post_comment` (lines 101-108)
- Posts inline comments with anchors built by `inline_anchor` (lines 33-50)
- Approves the PR via `bkt pr approve` if you selected **Approve** (lines 75-85)

All `bkt` commands execute through the `BktCommandRunner` abstraction, which calls `run_command_output("bkt", …)`.

## Key Implementation Details

### Repository Resolution and SHA Handling

The `parse_bitbucket_remote_url` function (lines 37-47 and 59-70 in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs)) validates that remotes point to bitbucket.org hosts and extracts the workspace and repository name. This guarantees that self-hosted Bitbucket Data Center instances are rejected during backend initialization.

Bitbucket's API returns 12-character commit hashes in PR payloads. tuicr expands these to full 40-character SHA1s via `promote_sha` (lines 27-44) to ensure stable session keys for review threads.

### Error Handling and Security

Authentication errors map to user-friendly messages through `map_bkt_error` (lines 93-111). If `bkt auth status` indicates an expired or missing token, tuicr surfaces a `TuicrError::Forge` variant with specific guidance rather than exposing raw CLI errors.

## Complete Workflow Example

Full setup and review submission:

```bash

# Install dependencies

brew install avivsinai/tap/bitbucket-cli

# Authenticate (one-time setup)

bkt auth login https://bitbucket.org --kind cloud --web-token
bkt auth status

# Navigate to repository and open PR

cd my-bitbucket-repo
tuicr pr 830

# Inside tuicr:

# 1. Review the diff

# 2. Press : to open command palette

# 3. Type 'submit' and select Comment or Approve

# 4. Confirm with 'y'

```

For automated testing without posting comments:

```bash
TUICR_BB_WORKSPACE=myteam \
TUICR_BB_REPO=my-service \
TUICR_BB_PR=830 \
cargo test bitbucket_live -- --ignored --nocapture

```

This executes the read-only test suite defined in the source that validates authentication and diff fetching without mutating the pull request.

## Summary

- tuicr requires the external `bkt` CLI for all Bitbucket Cloud operations; it never stores credentials internally
- Authentication uses `bkt auth login` with API tokens stored in the OS keychain
- The `BitbucketBktBackend` in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs) handles PR diff retrieval, comment posting, and approvals
- Bitbucket Cloud remotes are detected via `parse_bitbucket_remote_url`, which explicitly ignores Data Center instances
- Submit reviews by pressing `:submit` in the TUI, choosing between **Comment** or **Approve**, and confirming

## Frequently Asked Questions

### Does tuicr support Bitbucket Data Center or Server?

No. The `parse_bitbucket_remote_url` function explicitly validates hosts against `bitbucket.org`, `altssh.bitbucket.org`, and `api.bitbucket.org`. Self-hosted Data Center instances are rejected during remote URL parsing in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs).

### Where are my Bitbucket credentials stored?

tuicr does not store credentials. The `bkt` CLI stores your API token in the native OS credential store (macOS Keychain or Linux credential store). tuicr only checks authentication status by running `bkt auth status` before executing commands.

### How do I submit an approval instead of just comments?

In the tuicr TUI, press `:` to open the command palette, type `submit`, and select **Approve** from the picker. The `create_review` method will post your inline comments and then execute `bkt pr approve` to add the approval state to the pull request.

### What happens if my API token expires?

The `map_bkt_error` function in [`src/forge/bitbucket/bkt.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/bitbucket/bkt.rs) translates `bkt` authentication failures into `TuicrError::Forge` messages. You will see a prompt indicating the authentication error, and you must run `bkt auth login` again to refresh your token before resuming reviews.