CLI Reference¶

PikoCI provides three top-level commands: server, worker, and client, plus run for local execution, pipeline edit for local pipeline editing, and utility commands user-password and worker-token.

Global structure¶

pikoci server              [flags]          # Start the server
pikoci worker              [flags]          # Start a standalone worker
pikoci client              [flags] <cmd>    # Interact with the API
pikoci client audit list   [flags]          # Query the audit log
pikoci run                 [flags]          # Run a pipeline job locally
pikoci pipeline edit       <file> [flags]   # Edit a pipeline HCL file in the browser
pikoci user-password       [flags]          # Generate hashed passwords
pikoci worker-token        [flags]          # Generate a worker authentication token

client¶

Manage pipelines and jobs via the PikoCI API.

Global flags¶

Flag	Alias	Default	Required	Description
`--url`	`-u`	`localhost:8080`	yes	PikoCI server URL
`--jwt`			no	JWT token (if not provided, reads from `$XDG_CONFIG_HOME/pikoci/authentication`)

Authenticate and store the JWT locally.

pikoci client -u localhost:8080 login -u admin -p admin123

Flag	Alias	Required	Description
`--username`	`-u`	yes	Username
`--password`	`-p`	yes	Password

pipelines¶

Pipeline management commands. All require --team-canonical (default: main).

Flag	Alias	Default	Description
`--team-canonical`	`-tc`	`main`	Team scope

pipelines create¶

pikoci client -u localhost:8080 pipelines create \
  -n my-pipeline -c pipeline.hcl -v vars.json

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name
`--config`	`-c`	yes	Path to HCL config file
`--vars`	`-v`	no	Path to JSON vars file

pipelines update¶

pikoci client -u localhost:8080 pipelines update \
  -n my-pipeline -c pipeline.hcl --public

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name
`--config`	`-c`	yes	Path to HCL config file
`--vars`	`-v`	no	Path to JSON vars file
`--public`		no	Make the pipeline publicly visible

pipelines list¶

pikoci client -u localhost:8080 pipelines list

pipelines get¶

pikoci client -u localhost:8080 pipelines get -n my-pipeline

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name

pipelines graph¶

Export the pipeline as a DOT graph.

pikoci client -u localhost:8080 pipelines graph -n my-pipeline | dot -Tsvg > pipeline.svg

Flag	Alias	Default	Required	Description
`--name`	`-n`, `-pn`		yes	Pipeline name
`--format`	`-f`	`dot`	no	Output format

pipelines delete¶

pikoci client -u localhost:8080 pipelines delete -n my-pipeline

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Pipeline name

pipelines rename¶

pikoci client -u localhost:8080 pipelines rename -n my-pipeline --new-name new-pipeline

Flag	Alias	Required	Description
`--name`	`-n`, `-pn`	yes	Current pipeline name
`--new-name`		yes	New name for the pipeline

jobs¶

Job management commands. Require --team-canonical and --pipeline-name.

Flag	Alias	Required	Description
`--team-canonical`	`-tc`	yes	Team scope
`--pipeline-name`	`-pn`	yes	Pipeline name

jobs get¶

pikoci client -u localhost:8080 jobs get -tc main -pn my-pipeline -n my-job

Flag	Alias	Required	Description
`--job-name`	`-n`, `-jn`	yes	Job name

jobs trigger¶

Manually trigger a job.

pikoci client -u localhost:8080 jobs trigger -tc main -pn my-pipeline -n my-job

Flag	Alias	Required	Description
`--job-name`	`-n`, `-jn`	yes	Job name

users¶

User management commands.

users create¶

pikoci client users create --username newuser --password secret123

Flag	Required	Description
`--username`	yes	Username for the new User
`--password`	yes	Password for the new User

users list¶

pikoci client users list

users update¶

pikoci client users update --username myuser --full-name "My Name" --password newpass --admin

Flag	Required	Description
`--username`	yes	Username of the User to update
`--password`	no	New password for the User
`--full-name`	no	Full name for the User
`--admin`	no	Whether the User is an admin

users delete¶

pikoci client users delete --username myuser

Flag	Required	Description
`--username`	yes	Username of the User to delete

users change-password¶

Changes the password of the currently authenticated user.

pikoci client users change-password --old-password current --new-password newpass

Flag	Required	Description
`--old-password`	yes	Current password
`--new-password`	yes	New password

teams¶

Team management commands.

teams create¶

pikoci client teams create --name my-team

Flag	Required	Description
`--name`	yes	Name of the Team

teams list¶

pikoci client teams list

teams get¶

pikoci client teams get --canonical my-team

Flag	Required	Description
`--canonical`	yes	Canonical of the Team

teams update¶

pikoci client teams update --canonical my-team --name new-name

Flag	Required	Description
`--canonical`	yes	Canonical of the Team
`--name`	yes	New name for the Team

teams delete¶

pikoci client teams delete --canonical my-team

Flag	Required	Description
`--canonical`	yes	Canonical of the Team

teams members¶

Team member management. All subcommands require --team-canonical.

Flag	Required	Description
`--team-canonical`	yes	Team scope

teams members create¶

pikoci client teams members create --team-canonical my-team --username user1 --role admin

Flag	Required	Description
`--username`	yes	Username of the member to add
`--role`	no	Role for the member: `read`, `write`, `maintain`, `admin` (default: `maintain`)

teams members update¶

pikoci client teams members update --team-canonical my-team --username user1 --role admin

Flag	Required	Description
`--username`	yes	Username of the member to update
`--role`	no	Role for the member: `read`, `write`, `maintain`, `admin` (default: `maintain`)

teams members delete¶

pikoci client teams members delete --team-canonical my-team --username user1

Flag	Required	Description
`--username`	yes	Username of the member to remove

builds¶

Build management commands. All require --team-canonical, --pipeline-name, and --job-name.

Flag	Required	Description
`--team-canonical`	yes	Team scope
`--pipeline-name`	yes	Pipeline name
`--job-name`	yes	Job name

builds list¶

pikoci client builds list --team-canonical main --pipeline-name my-pipeline --job-name my-job

builds get¶

pikoci client builds get --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds delete¶

pikoci client builds delete --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds cancel¶

pikoci client builds cancel --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds retry¶

pikoci client builds retry --team-canonical main --pipeline-name my-pipeline --job-name my-job --build-number 1

Flag	Required	Description
`--build-number`	yes	Number of the Build

builds approve¶

Approve a build that is waiting for manual approval.

pikoci client builds approve --team-canonical main --pipeline-name deploy --job-name deploy --build-number 5 --message "LGTM"

Flag	Required	Description
`--build-number`	yes	Number of the Build
`--message`	no	Approval message

builds reject¶

Reject a build that is waiting for manual approval.

pikoci client builds reject --team-canonical main --pipeline-name deploy --job-name deploy --build-number 5 --message "not ready"

Flag	Required	Description
`--build-number`	yes	Number of the Build
`--message`	yes	Rejection reason

builds report¶

Export a build's full report as JSON.

pikoci client builds report --team-canonical main --pipeline-name deploy --job-name deploy --build-number 5
pikoci client builds report --team-canonical main --pipeline-name deploy --job-name deploy --build-number 5 --output report.json

Flag	Required	Description
`--build-number`	yes	Number of the Build
`--output`	no	Output file path (default: stdout)

resources¶

Resource management commands. All require --team-canonical and --pipeline-name.

Flag	Required	Description
`--team-canonical`	yes	Team scope
`--pipeline-name`	yes	Pipeline name

resources get¶

pikoci client resources get --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

resources trigger¶

pikoci client resources trigger --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

resources versions¶

pikoci client resources versions --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

resources webhook-regenerate¶

pikoci client resources webhook-regenerate --team-canonical main --pipeline-name my-pipeline --resource-canonical my-resource

Flag	Required	Description
`--resource-canonical`	yes	Canonical of the Resource

triggers¶

Trigger management commands. All require --team-canonical.

Flag	Required	Description
`--team-canonical`	yes	Team scope

triggers create¶

pikoci client triggers create --team-canonical main --name my-trigger --version '{"ref": "abc123"}'

Flag	Required	Description
`--name`	yes	Name of the Trigger
`--version`	yes	Version data as a JSON string

triggers list¶

pikoci client triggers list --team-canonical main --name my-trigger --after 0

Flag	Required	Description
`--name`	yes	Name of the Trigger
`--after`	no	List triggers after this ID (default: 0)

api-tokens¶

Manage API tokens for non-interactive authenticated access. See API Tokens for full documentation.

api-tokens create¶

Create a personal token (full user access):

pikoci client api-tokens create --name "my-script" --personal

Create a team-scoped token:

pikoci client api-tokens create --name "ci-deploy" --team-canonical main --role write

Flag	Required	Description
`--name`	yes	Name for the token (unique per user)
`--personal`	one of	Create a personal token with full user access
`--team-canonical`	one of	Team canonical for a team-scoped token
`--role`	with team	Role cap: `read`, `write`, `maintain`, `admin`
`--expires-at`	no	Expiration in RFC3339 format

--personal and --team-canonical/--role are mutually exclusive.

api-tokens list¶

pikoci client api-tokens list

api-tokens delete¶

pikoci client api-tokens delete --id 42

Flag	Required	Description
`--id`	yes	ID of the token to delete

api-tokens use¶

Store an API token locally for subsequent commands (replaces the login JWT).

pikoci client api-tokens use --token "pko_a1b2c3d4..."

Flag	Required	Description
`--token`	yes	The API token (`pko_...`)

To switch back to interactive login, run pikoci client login again.

export¶

Export the full database as a portable SQLite file. Requires admin credentials.

pikoci client -u localhost:8080 export -o backup.db

Flag	Alias	Required	Description
`--output`	`-o`	yes	Output file path for the SQLite export

This is also available via the web UI admin dropdown and as a GET /admin/export API endpoint.

audit¶

Audit log commands. Requires --team-canonical.

audit list¶

Query the audit log for a team. All filter flags are optional and can be repeated.

pikoci client audit list --team-canonical main --user alice --action pipeline.created --since 2026-01-01T00:00:00Z --until 2026-12-31T23:59:59Z --limit 100

Flag	Required	Description
`--team-canonical`	no	Team scope (default: `main`)
`--user`	no	Filter by actor username (repeatable, OR logic)
`--exclude-user`	no	Exclude entries by actor (repeatable)
`--action`	no	Filter by action type (repeatable, OR logic)
`--exclude-action`	no	Exclude entries with action type (repeatable)
`--pipeline`	no	Filter by pipeline canonical prefix (repeatable, OR logic)
`--since`	no	Show entries after this time (RFC3339)
`--until`	no	Show entries before this time (RFC3339)
`--limit`	no	Maximum number of entries to return (default: `50`)

run¶

Run a pipeline job locally without needing a server. Creates an ephemeral in-memory environment, executes the specified job, streams output, and exits with the job's status code.

pikoci run -p pipeline.hcl -j my-job

Flag	Alias	Default	Required	Description
`--pipeline-config`	`-p`		yes	Path to the pipeline HCL file
`--job`	`-j`		yes	Job name to execute
`--var`			no	Variable overrides in `key=value` format (repeatable)
`--vars`	`-v`		no	Path to a JSON vars file
`--resource`			no	Resource overrides in `type.name=path` format (repeatable, e.g. `git.my-repo=./local-dir`)
`--log-level`		`error`	no	Log level: `debug`, `info`, `warn`, `error`

Resource overrides¶

Use --resource to skip cloning and point a resource at a local directory instead:

pikoci run -p pipeline.hcl -j test --resource git.my-repo=./

This replaces the pull step for that resource with a symlink to the local path, so your task runs against local files.

pipeline edit¶

Open the browser-based pipeline editor for a local HCL file. Starts a minimal local HTTP server with the full editor UI (CodeMirror syntax highlighting, live graph preview, block navigation), pre-loaded with the file contents. Changes saved in the editor are written back to disk. No PikoCI server or authentication required.

pikoci pipeline edit ./pipeline.hcl

With a specific port:

pikoci pipeline edit ./pipeline.hcl --port 8181

Flag	Default	Required	Description
`--port`	`0` (random)	no	Port to listen on (`0` picks a random available port)

The server binds to 127.0.0.1 only. Press Ctrl+C to stop.

user-password¶

Generate a USERNAME:HASHED_PASSWORD string for the server's --users flag.

pikoci user-password -u myuser -p mypassword
# Output: myuser:$2a$10$...

Flag	Alias	Required	Description
`--username`	`-u`	yes	Username
`--password`	`-p`	yes	Plain-text password

worker-token¶

Generate a pre-signed worker authentication token. This avoids distributing the raw JWT secret to worker machines.

pikoci worker-token --jwt-secret my-secret
# Output: eyJhbG...

Flag	Default	Required	Description
`--jwt-secret`		yes	JWT secret used by the server

The server also logs a worker token on startup when --run-worker=false.

server¶

See Server Configuration.

worker¶

See Running Workers Separately.