#Sharkly CLI

The Sharkly CLI lets people, agents, and scripts work with Sharkly from a terminal. Use it to manage organization resources, register a computer for agent execution, inspect the local service, and automate repeatable workflows. When an Agent runs, command help and output follow the current UI language.

#Install the CLI

On macOS or Linux, run the official installer:

curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash

On Windows, run the official PowerShell installer:

powershell -NoProfile -ExecutionPolicy Bypass -Command "`$p = Join-Path `$env:TEMP 'sharkly_install.ps1'; Invoke-WebRequest 'https://file-assets.sharkly.ai/download/install.ps1' -UseBasicParsing -OutFile `$p; & `$p"

Verify the installation:

sharkly version

Update an installed CLI with:

sharkly update

macOS, Linux, and Windows all support sharkly update. The current Windows installer is AMD64 only.

If the target program file is in use during install or reconnect:

• occupancy from this product's CLI or local service: the installer stops it first, then replaces the file. After a successful replace it does not automatically start the service again; follow the page and run sharkly daemon start, or continue the connect wizard.
• occupancy from another program: an interactive terminal asks whether to stop it; declining cancels the install and keeps the old file. A non-interactive install (script or no terminal) reports the occupancy and exits without ending the other process or overwriting the old file.

Windows, macOS, and Linux follow the same behavior.

#Understand the authentication contexts

Sharkly uses separate credentials for separate purposes.

A personal access token does not register a computer. An install token does not create a human CLI login. Keep these paths separate when diagnosing authentication or local-service problems.

#Log in for human CLI access

Create a personal access token in Settings → Personal access tokens, then use the prompt-based login flow:

sharkly login --token

The CLI validates the token, saves it in the current profile, discovers the organizations available to the user, and sets a default organization when the profile does not already have one.

Check the current profile's authentication:

sharkly auth status
sharkly auth status --output json

Remove the saved token from the current profile:

sharkly auth logout

auth logout changes only local profile state. It does not revoke the token on the server. See Personal access tokens for creation, safe storage, rotation, and revocation.

#Register a computer and use the local service

The Computers screen provides a registration command containing a one-time sit_ install token. The token expires after 30 minutes and cannot be reused.

sharkly computer register --install-token sit_...

Registration writes the independent local-service session and normally restarts the local service. It does not use or modify the personal access token stored in a human profile.

Use the user-facing computer commands for routine checks:

sharkly computer status
sharkly computer status --output json
sharkly computer logs --lines 100
sharkly computer logs --follow

The daemon namespace exposes advanced local-service process operations:

sharkly daemon start
sharkly daemon start --foreground
sharkly daemon stop
sharkly daemon restart
sharkly daemon disk-usage --output json
sharkly daemon cleanup
sharkly daemon cleanup --confirm

daemon cleanup is a dry run unless --confirm is present. Prefer computer status and computer logs for routine diagnosis; use daemon when you specifically need process lifecycle, disk reporting, or cleanup controls.

The desktop app and Computer settings can change cleanup frequency, terminal-run retention, and the minimum free-space threshold. Those preferences take effect after the daemon restarts. The CLI commands and the desktop policy are complementary: automatic cleanup only reclaims safe terminal candidates and never deletes ~/.claude/worktrees.

#Configure endpoints and organization context

The Sharkly cloud defaults are:

• App: https://app.sharkly.ai
• API: https://api.sharkly.ai

Inspect the active profile configuration:

sharkly config show

The supported configuration keys are case-sensitive camelCase values:

sharkly config set serverUrl https://api.example.com
sharkly config set appUrl https://app.example.com
sharkly config set organizationId <organization-id>

For a one-off command, prefer explicit global flags instead of changing saved state:

sharkly --server-url https://api.example.com \
  --organization-id <organization-id> \
  task list --output json

#Use profiles correctly

A profile isolates human CLI configuration, including the saved personal access token, endpoint settings, and default organization.

sharkly --profile staging login --token
sharkly --profile staging auth status
sharkly --profile staging config show

Each Sharkly product and release channel has one local-service lifecycle. Named human profiles do not create additional local-service instances, and explicit --profile selection is not supported for local-service lifecycle, status, or log commands.

#Select an organization

List organizations available to the authenticated user:

sharkly organization list
sharkly organization list --full-id
sharkly organization list --output json

Set the current profile's default organization by ID, slug, or accepted ID prefix:

sharkly organization switch <organization-id-or-slug>

For scripts, prefer --organization-id so the target is visible in the command and does not depend on saved profile state.

#Use structured output in scripts

List commands usually default to tables. Detail and mutation commands often default to JSON, but scripts should request JSON explicitly instead of depending on a default.

sharkly --organization-id "$SHARKLY_ORG_ID" task list --output json | jq .
sharkly --organization-id "$SHARKLY_ORG_ID" task view "$TASK_ID" --output json | jq .

Useful global controls include:

• --color never to disable color.
• --quiet to suppress non-error status text.
• --debug to add diagnostics on standard error.

For robust shell scripts, use strict error handling and preserve pipeline failures:

set -euo pipefail

sharkly --color never --quiet \
  --organization-id "$SHARKLY_ORG_ID" \
  task list --output json |
  jq .

CLI exit status is 0 for success, 1 for command, validation, authentication, or remote API errors, and 2 for transient local-service or network conditions.

#Handle multiline content safely

Use files or standard input for multiline text, non-ASCII text, or content where backslashes must be preserved.

sharkly task create \
  --title "Investigate the failed release" \
  --body-file ./task-body.md \
  --output json

sharkly task comment "$TASK_ID" \
  --body-file ./result.md \
  --output json

printf '%s\n' "Build failed after dependency resolution." |
  sharkly task comment "$TASK_ID" --body-stdin --output json

The short --body form decodes supported escape sequences. Prefer --body-file or --body-stdin when exact content matters.

#High-value resource commands

#Tasks and comments

For an ordinary task, bug, or requirement, use sharkly task create. sharkly request create is only for Customer Requests, and only when Customer Requests are enabled for the Organization.

sharkly task list --output json
sharkly task list --status Published --status-changed-within 7d --output json
sharkly task search "authentication error" --output json
sharkly task view <task-id> --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment list <task-id> --output json
sharkly task comment <task-id> --body "Investigation started." --output json

When an attachment command accepts a task reference, prefer the task's full UUID. Some paths can resolve a public task identifier first, but the canonical UUID avoids ambiguity in attachment authorization and lookup. This guidance applies to attachment operations; other CLI commands may accept their documented task identifiers.

Filter by the latest transition into the task's current status with --status-changed-since <RFC3339> (inclusive), --status-changed-before <RFC3339> (exclusive), or --status-changed-within <duration>. Relative durations are positive integers followed by m, h, or d, use the server's current UTC time, and treat 7d as a continuous 7 × 24 hours. The relative option cannot be combined with explicit bounds. Historical tasks without an observed transition return statusChangedAt: null; the server does not infer it from creation or update timestamps, and bounded queries exclude those rows.

Filter by label with --label. The value can be a label id, name, or group/name, and the flag can be repeated:

sharkly task list --label <label> --output json

Filter by custom field with --field <field-reference>=<value>:

# Exact match on one custom field
sharkly task list --space HF --field "Customer Tier=VIP" --output json

# Multiple --field flags are ANDed and can combine with existing filters
sharkly task list --space HF --field "Blocked=true" --field "Target Date=2026-09-01"

The field reference is a custom-field UUID, or a field name that is unique in the current organization. If the name is ambiguous, missing, or not visible, the command fails and asks you to use the UUID. It does not guess.

Repeated --field flags are ANDed and can be combined with --status, --assignee, --project, and the other existing filters. Filtering happens on the server before pagination, so --limit / --offset apply to the filtered set. JSON output stays compatible and still returns each task's existing customFields.

Matching is type-aware and exact:

• Text / URL: full-string equality
• Number: numeric equality
• Boolean: true / false
• Date: YYYY-MM-DD
• Single-select / multi-select: option UUID, or a unique option label; a multi-select condition means the task contains that option
• Member: the same person references the rest of the CLI already uses

A task with no value for that field does not match an equality condition.

#Agent runs

sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json

Use run log --since when polling so the script retrieves only messages after the last processed sequence.

#Projects, Agents, Skills, and automations

sharkly project list --output json
sharkly project view <project-id> --output json
sharkly agent list --output json
sharkly agent view <agent-id> --output json
sharkly skill list --output json
sharkly skill view <skill-id> --output json
sharkly automation list --output json
sharkly automation view <automation-id> --output json
sharkly automation runs <automation-id> --output json

#Library collections and items

sharkly library manages your personal library and Space document collections:

sharkly library list --personal --output json
sharkly library tree --collection <collection-id> --output json
sharkly library search "release notes" --personal --output json
sharkly library view <item-id> --personal --output json
sharkly library link <item-id> --personal --output json

• Items (documents, files, folders, and tables): list, tree, search, view, doc, file, folder, table, edit, move, link, delete.
• Collections themselves: library collection list, create, edit, move, delete.

Item operations must name their scope explicitly:

• The scope is --personal (your own personal library in the current organization) or --collection <collection-id-or-unique-prefix>. The two are mutually exclusive, and exactly one is required. --parent only names a parent node inside that scope; it does not replace the scope.
• Collection commands take --space <space-id-or-number> and verify that the collection belongs to that Space.

Risky writes — deleting, replacing a document's full text, replacing a file, editing a CSV, and moving an item across scopes — support -y/--yes to skip confirmation and --dry-run to validate and show the effect without writing. In a non-interactive environment such as a script or an Agent, a risky operation without --yes fails instead of waiting for input.

--output selects the output format only (json, table, or text). To choose where a downloaded file lands, use -o/--output-dir (the current directory by default); replacing an existing local file also requires --overwrite.

#Computers and runtimes

sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer activity <computer-id> <runtime-id> --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json

#Discover the installed command contract

Use runtime help for the exact flags supported by the installed version:

sharkly --help
sharkly task --help
sharkly task create --help
sharkly computer --help

The CLI also exposes its registry and curated scenarios:

sharkly schema task create --format json
sharkly tldr task
sharkly help formatting
sharkly help exit-codes

#Troubleshoot Runtime detection and login

If the Computer is online but a Runtime is Not detected, install the tool the Runtime actually uses. Some Runtimes need the CLI, not the desktop app; follow the Computer detail page. After installing, rescan or restart the local service.

If detection or chat reports that a Runtime is unsigned-in or unauthorized, run the command shown on the page in a terminal on that Computer. That login is separate from sharkly login --token.